# workcode

**Repository Path**: lv-hang12316/workcode

## Basic Information

- **Project Name**: workcode
- **Description**: 只做更符合个人习惯的编辑器
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: dev
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-25
- **Last Updated**: 2026-08-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# WorkCode

WorkCode 是面向个人与小型团队的桌面工程执行助手。它以 OpenCode 的多模型编码能力为基础，增加了面向完整交付的任务编排、专家代理分派、过程可视化、AI 审查和本地知识管理能力。

它的目标不是只生成一段代码，而是把一个自然语言目标推进到可核验的交付状态：理解需求、拆分任务、执行修改、运行验证、处理失败、审查变更并汇总结果。

> 当前仓库包含 WorkCode 的开发版和 Windows 桌面预览打包链路。核心运行时仍处于持续迭代中，生产使用前请在目标项目中完成独立验证。

## 目录

- [核心能力](#核心能力)
- [内置任务链路与路由](#内置任务链路与路由)
- [使用方式](#使用方式)
- [模型、MCP 与知识资源](#模型mcp-与知识资源)
- [桌面端与打包](#桌面端与打包)
- [架构与目录](#架构与目录)
- [开发、测试与贡献](#开发测试与贡献)
- [安全边界](#安全边界)
- [许可证](#许可证)

## 核心能力

### 从目标到交付的工程闭环

WorkCode 将一次任务组织为可追踪的工程流程，而不是一次性的聊天响应。

- 接收自然语言目标，区分简单请求与复杂、多步骤请求。
- 对复杂工作生成迭代计划，按“分析 -> 计划 -> 执行 -> 验证”推进。
- 对清晰的单领域任务走快速路径：创建紧凑任务节点后，直接交给匹配的专家代理。
- 在每次子任务返回后保留完成度、修改文件、验证证据、风险和下一步等结构化摘要。
- 验收失败、结果不完整或遇到阻塞时，自动形成后续修复任务，而不是把一次子任务返回当作整体完成。
- 只有目标已实现且存在具体验证证据，或用户明确同意停止时，才允许结束任务。

### 可见、可控的桌面工作台

桌面端以编辑器式会话界面承载执行过程，便于在自动化与人工介入之间切换。

- 会话中的任务、计划、验证和变更面板展示目标、阶段、依赖、进度、文件变更和失败信息。
- 右侧可打开知识库、Skills、MCP 工具和记忆视图，资源按需使用，避免无关上下文膨胀。
- 提供用户输入时间线、当前/后续工作列表与任务暂停、恢复、取消等控制入口。
- 提供 Agent Office 场景面板，以当前任务、委派、回传和验收状态展示协作进展。
- 具备 Git 差异审查与 AI Review 模式，可在变更上下文中检查并接受或拒绝审查项。

### 内置工程质量约束

- 支持任务图、可恢复检查点、受限重试、终态处理和缺失能力分支。
- 规划链路覆盖新项目、功能开发、缺陷修复、页面美学审查与最终交付等工作类型。
- 代码任务要求返回聚焦验证的证据；仅修改文件而没有验证观察，不能被视为完成。
- 代码变更可同时生成 `.workcode/reviews/<session_id>/<message_id>.json` 审查元数据，记录改动意图、实现方式、影响范围与必要的行级解释。
- 审查说明保存在 `.workcode/reviews` 中，不写入业务源代码；界面可利用本地规则解释显而易见的语法，减少模型调用和冗余说明。

### 多模型与开发者工具生态

- 通过统一的 LLM 路由层接入 OpenAI、Anthropic、Google Gemini、Amazon Bedrock、Azure OpenAI、Cloudflare AI Gateway/Workers AI、GitHub Copilot、OpenRouter、xAI 等，以及 OpenAI 兼容服务。
- 提供 CLI、终端 TUI、浏览器界面、无头 HTTP 服务和 Electron 桌面端。
- 支持 Provider 登录与凭据管理、模型查询、会话导入/导出、GitHub/PR 流程、插件和 MCP 服务管理。
- 提供 SDK、插件、核心、LLM、服务器和 UI 等独立包，适合在现有工作流中二次集成。

## 内置任务链路与路由

WorkCode 的协调者称为 **workfather**。它负责理解、计划、路由、监督、验收和最终汇总；实际执行由受限的短生命周期专家代理完成。这样可以让父会话保留目标和证据，而不堆积完整工具日志与长提示词。

```text
用户目标
  |
  +--> 信息是否足够？ ---- 否 ----> 一次最小澄清问题
  |          |
  |          是
  v
workfather：建立/刷新迭代计划
  |
  +--> 简单单域请求：快速分派
  |
  +--> 复杂请求：分析 -> 计划 -> 分派 -> 验证
                                      |
                                      v
                      coding / docs / file / explore / summarizer
                                      |
                                      v
             结构化结果：完成度、证据、风险、变更、下一步
                                      |
                                      v
               workfather 验收 -- 未通过 --> 定向修复并重新分派
                                      |
                                   通过 v
                                  最终交付
```

### 路由原则

路由依据“用户意图 + 操作对象 + 最终交付物”综合判断，而不是只匹配单个关键词。对于同一个词，交付物不同会走不同链路：

| 用户目标 | 路由 | 原因 |
| --- | --- | --- |
| “给后台加入 CSV 导入导出功能” | `coding` | 交付物是应用能力、接口和代码。 |
| “把这些 CSV 导出成 XLSX” | `file` | 交付物是已转换的文件。 |
| “写交通管理系统汇报 PPT 大纲” | `docs` | 交付物是文字内容。 |
| “检查 4096 端口被什么进程占用” | `explore` | 属于环境/系统检查。 |
| “整理本次改造的风险和下一步” | `summarizer` | 交付物是紧凑摘要与决策信息。 |

### 专家代理

| 专家 | 负责范围 | 约束 |
| --- | --- | --- |
| `coding` | 功能开发、Bug 修复、重构、UI、API、配置、测试、构建与桌面预览验证 | 在委派范围内直接修改并提供验证证据；不再继续分派子代理。 |
| `docs` | 文档、PPT 文案、报告、讲稿、方案、发布说明等纯写作交付物 | 不用于编辑项目代码、UI、配置、测试或应用行为。 |
| `file` | 文件转换、导入/导出、素材整理、批量文件处理与产物校验 | 回报输入、输出和验证证据，保证可追溯。 |
| `explore` | 代码库检索、问题调查、环境与系统检查 | 以只读探索为主，适合快速或深度定位。 |
| `summarizer` | 摘要、上下文清理、决策记录、风险与下一步提取 | 默认仅保留读取权限，输出紧凑结论。 |

### 执行与验收规则

1. workfather 先判断核心事实、源文件、目标对象或业务规则是否缺失；缺失且会导致编造内容时，才发起最小澄清。
2. 每个专家代理接收结构化任务包，其中包含目标、验收条件、作用范围、约束、可用资源索引和用户偏好。
3. 专家回传 `completed`、`partial`、`blocked` 或 `failed` 状态，以及 0-100 的完成度、证据、风险和后续建议。
4. 父协调者检查结果和验证证据；`partial`、`blocked`、`failed` 或未验证的结果都会进入后续动作，而非被宣告完成。
5. 对代码工作，审查代理只生成解释元数据，不修改源代码；实现和审查可分离执行。

## 使用方式

### 环境要求

- [Bun](https://bun.sh) 1.3 或更高版本。
- Node/Electron 依赖由工作区安装过程管理。
- Windows 桌面打包目前仅支持 Windows。
- 至少配置一个可用的模型服务商凭据，或使用相应 Provider 的环境变量。

### 安装依赖

```powershell
bun install
```

### 开发运行

在仓库根目录启动本地 CLI/TUI：

```powershell
bun dev
```

指定工作目录：

```powershell
bun dev D:\path\to\your-project
```

启动无头服务，默认端口为 `4096`：

```powershell
bun dev serve
```

启动浏览器界面：

```powershell
bun dev web
```

启动桌面开发版：

```powershell
bun --cwd packages/desktop dev
```

前端单独开发时，先启动服务端，再启动前端：

```powershell
bun dev serve
bun --cwd packages/app dev
```

### 常用 CLI 命令

```powershell
# 查看可用命令与版本
bun dev --help
bun dev --version

# 管理模型服务商凭据
bun dev providers list
bun dev providers login

# 浏览可用模型、管理 MCP 与会话
bun dev models
bun dev mcp --help
bun dev session --help

# 运行或接入已有服务
bun dev run --help
bun dev attach --help
```

开发期的 `bun dev` 与构建后的 `opencode` 命令使用相同 CLI 接口；发布后的命令将仍显示为 `opencode`，这是上游运行时的当前命令名。

## 模型、MCP 与知识资源

### 模型服务

使用 `providers login` 完成交互式授权，或按 Provider 约定设置环境变量。可使用下列命令核对已经保存的凭据与生效的环境变量：

```powershell
bun dev providers list
```

运行时通过统一路由层处理模型端点、认证、请求格式和流式响应差异。需要使用私有网关或 OpenAI 兼容端点时，应通过项目配置声明对应 Provider、端点和模型，避免把密钥写进源码或提交到仓库。

### MCP、Skills 与知识库

MCP、Skills 和知识资源在默认流程中以“资源索引”形式提供给协调者。只有当前任务确实需要时，专家代理才会展开具体内容，因此可避免把全量知识、工具清单或长文档塞进每次模型请求。

```powershell
# 查看 MCP 子命令
bun dev mcp --help

# 交互式添加 MCP 服务的入口
bun dev mcp add --help
```

在桌面工作台中可以查看和维护知识库、Skills、MCP 工具与会话记忆。资源是否可被使用仍受当前会话的权限模型约束。

## 桌面端与打包

### Windows 免安装预览版

生成可直接运行的预览目录：

```powershell
bun --cwd packages/desktop run package:preview
```

产物通常位于：

```text
packages/desktop/dist/preview/win-unpacked/WorkCode Preview.exe
```

预览版会保留本地登录、会话和用户数据，适用于持续调试。

### Windows 安装包

```powershell
bun --cwd packages/desktop run package:installer
```

安装包构建前会清理预览用户数据和登录状态，以便从干净环境验证；产物位于 `packages/desktop/dist/preview`。

复用现有构建产物时可跳过重新构建：

```powershell
bun --cwd packages/desktop run package:preview -- --skip-build
bun --cwd packages/desktop run package:installer -- --skip-build
```

指定发布版本：

```powershell
bun --cwd packages/desktop run package:installer -- --version 1.20.0
```

仓库根目录的 `打包器` 目录还提供了面向日常发版的 Windows 图形打包器。详细流程见 [packages/desktop/PACKAGING.md](packages/desktop/PACKAGING.md)。

## 架构与目录

| 路径 | 说明 |
| --- | --- |
| `packages/opencode` | CLI、服务端、会话、代理、工具、任务编排和 Provider 运行逻辑。 |
| `packages/opencode/src/session/orchestration.ts` | WorkCode 迭代计划、任务包、专家路由和验收提示词。 |
| `packages/core` | 共享领域模型、配置、存储、权限、项目与底层运行时能力。 |
| `packages/llm` | Schema-first LLM 核心、Provider 协议适配和模型路由。 |
| `packages/app` | SolidJS 前端：会话、任务/计划/验证/变更面板、AI 审查、知识和记忆界面。 |
| `packages/desktop` | Electron 桌面壳、IPC、Windows 预览版与安装包打包脚本。 |
| `packages/session-ui` | 会话消息、任务对话和审查相关的可复用 UI。 |
| `packages/sdk/js` | JavaScript SDK；变更 API 后可用 `./packages/sdk/js/script/build.ts` 重新生成。 |
| `packages/plugin` | 插件系统与扩展接口。 |
| `specs` | 工程助手设计、任务清单与会话运行时设计说明。 |

## 开发、测试与贡献

安装依赖后，请在具体包目录执行类型检查和测试，避免在仓库根目录执行测试命令：

```powershell
# 核心运行时
Set-Location packages/opencode
bun typecheck
bun test

# 前端
Set-Location ..\app
bun typecheck
bun test

# 核心包
Set-Location ..\core
bun typecheck
bun test
```

恢复到仓库根目录后，可按需执行：

```powershell
bun run lint
```

贡献时请遵循以下约定：

- 默认分支为 `dev`；比较改动时使用 `dev` 或 `origin/dev`，不假定存在本地 `main`。
- 分支名使用不超过三个单词的连字符形式，例如 `session-recovery`。
- 提交信息采用 Conventional Commits，例如 `feat(app): add review panel`。
- TypeScript 类型检查使用 `bun typecheck`，不要直接运行 `tsc`。
- 变更 SDK API 后运行 `./packages/sdk/js/script/build.ts` 生成 JavaScript SDK。
- 详细工程规范见 [AGENTS.md](AGENTS.md)，贡献流程见 [CONTRIBUTING.md](CONTRIBUTING.md)。

## 安全边界

- 模型密钥、令牌和私有网关地址应通过 Provider 登录、环境变量或本地配置管理，绝不提交到版本库。
- 文件写入、命令执行、外部访问和高风险操作仍由权限模型约束；自动分派不等同于绕过确认。
- 当运行 `bun dev web` 或 `serve` 对外暴露服务时，请设置 `OPENCODE_SERVER_PASSWORD`；未设置密码的服务会以无保护状态启动。
- AI 生成结果需要在目标环境中执行测试、构建或人工审查后再进入生产。任务面板中的“完成”反映当前执行状态，不替代发布审批。
- `.workcode/` 保存本地任务或审查辅助数据，通常不应作为业务源文件处理；是否纳入版本控制应按团队流程决定。

## 许可证

本项目采用 [MIT License](LICENSE)。上游 OpenCode 及第三方依赖仍遵循各自许可证。