1. 准备本地开发环境
使用 package.json 指定范围内的 Node.js，然后按 lockfile 安装固定依赖。
git clone https://github.com/CatCatUncle/openworkbuddy.git
cd openworkbuddy
npm ci
npm start打开服务输出的本机地址。个人配置、API Key、任务数据和生成文件不要提交到 Git。首次启动说明见 《安装与启动》。
2. 阅读代码架构
server.js 和应用入口负责把服务接起来。Agent 主循环在 src/agent/；工具实现、模型适配、业务域、安全、存储和平台能力放在 src/ 下。
src/agent/：Agent 主循环、工具派发和权限闸门。src/tools/：按职责拆分的工具实现。src/core/：模型、计费、安全、记忆、扩展和自动化。src/domains/：账号、内容、媒体、资料库等业务域。src/server/routes/、src/cli/、src/im/、src/desktop/：各应用自己的入口部件。public/：网页结构、样式和按顺序加载的经典脚本。
依赖按项目规定的层级向下流动，应用模块之间保持独立；需要共享能力时放入较低层或通过参数注入。改目录前先读 《代码架构》。
3. 添加或修改 Agent 工具
- 在
src/agent/tools.js中查看工具定义和派发，再到相关src/tools/文件定位实现。 - 限制输入范围，定义必填字段、边界、允许路径和清楚的报错行为。
- 文件写入和命令执行沿用现有权限及审批闸门，不要绕开它们另开通路。
- 返回模型和界面都能理解的结果；日志不要带密钥或无关文件正文。
- 在
test/添加成功、拒绝和畸形输入的用例，确保危险路径被拦。
新增 HTTP 路由时沿用鉴权方式，在入口校验请求，并在读取或写入用户数据前核对归属。
4. 添加 Skill 或连接器预设
Skill 通常放在 skills/<名称>/，由 skill.md 和 YAML frontmatter 中的名称、描述组成。步骤要具体、范围明确，并能安全地重复执行；模板和脚本放在同目录。
连接器预设在 src/core/ext/mcp-catalog.js。只提交字段名和占位信息，不能放有效凭证。补齐必填环境变量、文档链接、分类以及本地命令或远程 URL 类型。覆盖命令不存在、Secret 为空、连接器关闭和配置错误的情况。
完整用法见 《技能、连接器与插件》。
5. 修改前端
主界面入口是 public/index.html，脚本按顺序拆在 public/js/ 下，并共享经典脚本全局作用域。保持加载顺序，不添加内联事件处理器。
- 用户可见文字加入
public/js/i18n.js，分别验证中文和英文界面。 - 沿用已有设计令牌，使用语义控件、键盘焦点和无障碍名称。
- 渲染用户输入时在边界转义；不可信文本用文本节点，不拼入 HTML。
- 多人功能同时核对服务端权限和界面显示，不能只隐藏按钮。
6. 验证行为和安全
迭代时先运行最相关的套件，发布前再跑完整闸门。
node test/all.js --only e2e
npm test全量测试包括架构、权限、本地化、打包和端到端检查。部分桌面与打包测试需要平台依赖，并可能运行数分钟。
- 不要提交 API Key、访问令牌、本机配置、会话导出、客户资料或构建产物。
- 除了正确流程，也要测试越界路径和权限不足时的拒绝结果。
- 测试使用临时数据目录和假凭证，不连接个人账号。
- 用户行为发生变化时，同时更新中英文变更记录。
7. 参与贡献和准备发布
让改动范围集中，说明用户可见行为，并添加能在回归时失败的测试。提交前检查最终 diff，清理本机路径和凭证。
发布由 Git tag 触发。先更新 package 版本和变更记录，跑完整测试，然后推送匹配的 vX.Y.Z tag。工作流会核对版本号、先测试再打包，并上传各平台产物。
任务、连接器与审查实现
模块入口、OAuth 回调归属、分块回退冲突、操作录制隐私、团队费用与专项测试命令见任务与连接器开发参考.
英文界面对可见控件调用 I18N.untranslated，有漏翻就判失败；用户原文必须显式标记，避免误翻和误报。