@cangjielang/aceharness
v1.0.0-rc.14
Published
ACEHarness - Agent Centric Engineering Harness (From Cangjie Team)
Readme
ACE Harness (Agent Centric Engineering Harness)
English | 中文
ACEHarness 是一个面向工程任务的本地 AI Multi-Agent 协作平台。它把 Spec Driven Development、状态机工作流、Supervisor 智能路由、对抗式迭代、多 Agent 议场、Git 基线断点、多层永久记忆、Notebook 知识沉淀、Skill 能力扩展和模型/引擎诊断组合在一起，让复杂研发任务可以被规划、执行、协作、审查、回退、恢复和复盘。
目录
产品全景
ACEHarness 按“规划、执行、协作、沉淀、扩展、接入”组织工程任务闭环；下图展开核心能力入口，便于从产品全景进入日常工作流。
一人公司模式
一人公司模式把 /office 办公室变成个人 AI 团队桌面，用户用一句话组建或调整产品、设计、工程、增长、运营等 Agent 角色，并通过工位、组织图、私聊/群聊和长期记忆持续协作。
快速开始
前置条件
- Node.js
>= 22.13.0/ npm>= 9：运行服务与 npm CLI 包 - AI 执行引擎：
claude-code、kiro-cli、opencode、nga、codegenie、cursor、codex、trae-cli、magic-cli等至少一种
安装与运行
快速开始：
npm install -g @cangjielang/aceharness
ace --help
ace
# ✔ 请选择语言 › 中文
# [ACE] 欢迎使用。首次启动将初始化本地运行配置。
# ...
# [ACE] 正在启动服务：http://127.0.0.1:3000
# [ACEHarness] Server ready on http://0.0.0.0:3000
# [ACE] 请在浏览器中打开 http://127.0.0.1:3000首次访问会进入初始化流程：创建管理员、选择语言、配置默认工作目录和可用 AI 引擎。后续团队成员可通过注册页申请账号，由管理员审核后使用。进入控制台后，可通过 Onboarding 查看完整使用路径和模块引导。
如果您是开发者：
git clone https://gitcode.com/Cangjie-SIG/ACEHarness.git && cd ACEHarness
# 安装依赖
npm install
# 本地调试：npm run dev 会先构建 CLI，再启动开发服务
ACE_HOST=0.0.0.0 ACE_PORT=3000 npm run dev
# Windows PowerShell:
# $env:ACE_HOST="0.0.0.0"
# $env:ACE_PORT="3000"
# npm run dev
# 生产模式：首次启动或代码更新后先构建
npm run build
ACE_HOST=0.0.0.0 ACE_PORT=3000 npm start启动后访问 http://127.0.0.1:3000。如果使用 PowerShell 运行生产模式，同样先设置 $env:ACE_HOST 和 $env:ACE_PORT，再执行 npm start。
ACE Service 的全局 CLI 用法：
ace # 启动 ACE Service
ace start # 显式启动 ACE Service
ace service # 查看并停止当前受管的 ACE 实例
ace update # 更新到 npm latest 版本
ace update beta # 更新到指定 npm tag 或版本号，例如 beta / release / 1.0.0-beta.66启动向导支持直接开启后台运行；如同时启用守护进程，ACE 会以 daemon 模式托管后台服务，并在异常退出后自动拉起。执行 ace update 时会检查这些受管的 ACE 实例；交互模式下可选择停止后更新、继续更新但不停止，或取消更新。脚本中可用 ace update --stop-running 先停止运行中的实例，或用 ace update --force 在实例仍运行时继续安装，运行中的服务重启后才会使用新版本。
核心机制
ACEHarness 的核心机制已整合在上方工作台图中：从 Spec 计划与状态机执行，到 Supervisor 路由、对抗评审、议场协作、记忆沉淀、能力扩展、模型诊断和外部渠道接入，形成可治理的工程闭环。
系统架构
注：
- 浏览器前端承接首页对话、工作流工作台、议场、笔记本、工作区和设置诊断等主要页面。
- 服务入口统一处理启动、页面路由、接口路由、鉴权、协作长连接和流式事件。
- 业务服务负责任务、对话、状态机、规范开发、议场、笔记本、工作区、渠道、能力市场和模型诊断。
- 运行与执行层通过调度器、进程管理器、引擎工厂、上下文恢复和结果归一化连接多种执行后端。
- 本地数据根目录沉淀配置、数据、缓存、日志、工作区、运行记录、笔记本和能力包，外部渠道消息进入同一上下文。
产品界面
ACEHarness 的界面围绕日常工程工作流组织：
- 首页对话：承接普通 AI 对话、工作流创建、议场入口和微信 ClawBot 会话绑定。
- 议场：以话题或工作流为中心组织多 Agent 群聊，适合方案讨论、分歧收敛和执行复盘。
- 工作流工作台：展示状态机运行、步骤流式输出、人工检查点、Preflight 结果、Git 步骤变更和运行恢复；状态机步骤支持嵌入另一个状态机作为子工作流执行。
- Workspace 与变更：内嵌文件编辑、目录浏览、Git diff、步骤级变更和 baseline 对比。
- Cangjie Notebook：沉淀文档、笔记、运行产物和复盘材料，支持个人/团队空间、协作编辑、快照和分享。
- 模型/引擎诊断台：用标准 probe 评估模型与执行后端，定位 SDK、ACP、HTTP driver 和流式事件问题。
- 治理与接入：账号、用户、系统设置、渠道接入和 API 文档作为治理入口串联所有页面。
工作流案例
查看四个案例的根因路径、执行数据与交付结果：工作流案例文档。
配置与引擎
ACEHarness 的配置主要由启动向导、引擎管理页和环境变量共同决定。当前仓库支持 claude-code、kiro-cli、opencode、nga、codegenie、cursor、codex、trae-cli、magic-cli 等本地执行后端；模型/引擎诊断台可验证连接、流式事件、结构化输出、代码、数学和推理能力。
ACP 执行文件覆盖
NGA、CodeAgent 和 CodeGenie 的 ACP 适配器默认按各自的 CLI 名称从配置搜索路径和 PATH 中查找。需要使用非标准安装位置时，可设置下列变量覆盖对应的可执行文件：
| 变量 | 适配器 | 默认候选 | 说明 |
|------|--------|----------|------|
| ACEH_NGA_COMMAND | NGA | ngagent，再回退 nga | NGA ACP CLI 可执行文件路径或 bare command name |
| ACEH_CODEAGENT_COMMAND | CodeAgent | codeagent | CodeAgent ACP CLI 可执行文件路径或 bare command name |
| ACEH_CODEGENIE_COMMAND | CodeGenie | codegenie | CodeGenie ACP CLI 可执行文件路径或 bare command name |
显式覆盖优先级最高，设置后不会悄悄回退到其他候选命令；请传入单个文件路径或 bare command name，不能包含 acp、--cwd 或其他参数。路径包含空格时无需自行添加 shell 引号：
$env:ACEH_NGA_COMMAND = 'C:\Program Files\NGA\ngagent.cmd'
$env:ACEH_CODEAGENT_COMMAND = 'C:\Program Files\CodeAgent\codeagent.cmd'
$env:ACEH_CODEGENIE_COMMAND = 'C:\Program Files\CodeGenie\codegenie.cmd'这些变量只控制 ACP CLI 适配器，不影响 ACE_NGA_SDK_COMMAND、ACE_NGA_BIN、ACE_CODEGENIE_SDK_COMMAND 或 ACE_CODEGENIE_BIN。后四项属于 SDK 集成配置，不能替代 ACP 可执行文件覆盖。
ACE Service
server.js 会在启动时加载 .env、.env.local 以及当前模式对应的 .env.development* / .env.production*；shell、进程管理器或启动脚本里已存在的环境变量优先级更高，不会被文件覆盖。
核心启动与运行目录变量：
| 变量 | 说明 | 默认值 / 优先级 |
|------|------|-----------------|
| ACE_HOST | 服务监听地址 | 127.0.0.1 |
| ACE_PORT | ACEHarness 服务端口 | 3000 |
| PORT | 通用服务端口 | 优先级高于 ACE_PORT |
| BASEURL / BASE_URL | 反向代理子路径或站点前缀，用于生成应用路由和静态资源访问前缀 | 未设置时为空；示例：/ace 或 https://example.com/ace |
| ACE_HOME | ACE 运行根目录，决定 config/、data/、cache/、logs/、workspace/ 等运行时数据位置 | 未设置时按平台回退 |
| APPDATA | Windows 下 ACE_HOME 的回退根目录 | <APPDATA>/ACEHarness |
| XDG_DATA_HOME | Linux / macOS 下 ACE_HOME 的回退根目录 | <XDG_DATA_HOME>/aceharness |
反向代理到子路径时，需要在构建和启动时使用同一个 BASEURL。例如将外部 /ace/ 代理到本地 http://127.0.0.1:3000/：
BASEURL=/ace ACE_HOST=127.0.0.1 ACE_PORT=3000 npm run build
BASEURL=/ace ACE_HOST=127.0.0.1 ACE_PORT=3000 npm start开发模式也可以直接：
BASEURL=/ace ACE_HOST=127.0.0.1 ACE_PORT=3000 npm run devWindows PowerShell:
$env:BASEURL="/ace"
$env:ACE_HOST="127.0.0.1"
$env:ACE_PORT="3000"
npm run dev| ACE_INSTALL_ROOT | 安装根目录；用于定位 server.js、configs/、dist/ 等安装内容 | 未设置时由启动器自动设为当前安装目录 |
| ACE_LOCALE | ACE CLI 与服务默认语言 | 优先级高于 LANG / LC_ALL |
| LANG | 语言回退变量 | 在 ACE_LOCALE 未设置时参与解析 |
| LC_ALL | 语言回退变量 | 在 ACE_LOCALE、LANG 未设置时参与解析 |
| NODE_ENV | 运行模式；同时影响 .env* 加载和部分调试默认值 | production（受管服务子进程默认如此） |
| ACE_MAX_OLD_SPACE_MB | 服务进程 V8 老生代堆上限（MB），覆盖自动计算值 | 默认按物理内存 60% 取值，夹在 4096–8192 |
| ACE_MEM_WATCHDOG | 内存看门狗开关；超阈值时在 OOM 前优雅重启 | 默认开启；设为 0 关闭 |
| ACE_MEM_SOFT_PCT | 软阈值（占堆上限比例）；仅在空闲时触发优雅重启 | 0.80 |
| ACE_MEM_HARD_PCT | 硬阈值（占堆上限比例）；无条件强制重启以避免 OOM | 0.92 |
| ACE_MANAGED | 内部标记：标识服务进程受 daemon 监管，允许看门狗自重启 | 由 CLI 自动设置，无需手动配置 |
对外地址与渠道恢复变量：
| 变量 | 说明 | 默认值 / 优先级 |
|------|------|-----------------|
| ACE_PUBLIC_ORIGIN | 对外访问的绝对地址；用于 webhook、回调 URL、官方微信桥接等场景 | 优先级最高 |
| ACE_WECHAT_AUTO_RESTORE | 是否在服务启动后自动恢复官方微信 bridge | 默认开启；设为 0 / false 可关闭 |
| ACE_WECHAT_RESTORE_DELAY_MS | 官方微信 bridge 自动恢复延迟（毫秒） | 3000 |
渠道接入
ACEHarness 现已支持把工作流运行时对话、人工检查点和多 Agent 议场桥接到外部聊天平台。当前内置了 Feishu、DingTalk、WeChat Bridge、Generic Webhook 四类 provider 模板，可通过 POST /api/channels/setup 一键生成 webhook 和共享密钥，再由外部平台或桥接器把消息投递到 /api/channels/inbound/:integrationId。
详细说明见：渠道接入文档。
文档
- 工作流模板用户指南：将现有工作流另存为模板，以及通过内置、个人或团队模板创建工作流
- 工作流案例：四个真实/复盘案例的完整细节
- ACP Code Agent 集成检查清单：ACP Code Agent 接入与验证参考
- 一人公司模式功能介绍：基于
/office的个人 AI 团队、组织草案、工位协作和记忆模式说明
开发参考
项目结构
| 路径 | 说明 |
|------|------|
| bin/ | npm CLI 入口，ace 命令会加载构建后的 dist/cli.js |
| server.js | 自定义 Next.js 启动器，负责加载 .env*、启动 HTTP 服务和 Notebook 协作 WebSocket |
| src/app/ | Next.js App Router 页面与 API 路由 |
| src/components/ | 工作台、对话、Notebook、工作区等前端组件 |
| src/lib/ | 工作流引擎、Spec Coding、认证、运行记录、调度、模型和工作区等核心逻辑 |
| configs/ | 工作流配置与内置 Agent/角色配置 |
| skills/ | 随包分发的 Skills |
| messages/ | 中英文界面文案 |
| public/ | README 和前端使用的图片资源 |
| tests/ | Vitest 测试用例 |
常用命令
命令来源：package.json。
npm run dev # 本地开发，先构建 CLI，再以 dev 模式启动服务
npm run build # 构建 CLI 和 Next.js 应用
npm start # 启动生产构建
npm test # 运行 Vitest 测试
npm run test:components # 使用 jsdom 环境运行组件测试
npm run lint # 运行 Next.js lint
npm run check:engines # 检测本机可用 AI 执行引擎
npm run clean # 清理 dist、.next、dist-build
npm run release:tag -- 1.0.0-rc.13 --dry-run # 维护者执行完整发布预演
npm run publish:beta # 构建并以 beta tag 发布 npm 包正式 npm + GitCode 发布统一使用 docs/releasing.md 中的 tag 发行流程。
CLI 命令来源：src/cli.ts。
ace # 启动 ACEHarness
ace start # 启动 ACEHarness
ace service # 查看并停止 ACE 服务
ace update # 更新到 npm latest 版本
ace update beta # 更新到指定 npm tag 或版本号
ace reset --force # 重置本地 ACE 配置
ace --help # 查看帮助测试与质量
测试框架为 Vitest，配置位于 vitest.config.ts，默认匹配 tests/**/*.test.ts 和 tests/**/*.test.tsx。
npm test
npm run test:components
npm run lint技术栈
| 类别 | 技术 |
|------|------|
| 应用框架 | Next.js 16.1、React 18.2、TypeScript 5 |
| UI 与交互 | Tailwind CSS 3.4、Shadcn/ui、Radix UI、Base UI、Framer Motion、Vaul |
| 编辑与协作 | Tiptap 3、Yjs、y-websocket、Monaco Editor |
| 工作流与配置 | Zod 4、YAML、node-cron、tar-stream、unzipper、yazl |
| 可视化 | ReactFlow 11、Recharts 3、Mermaid 11 |
| 表单与拖拽 | React Hook Form 7、@dnd-kit |
| Markdown 与文档 | react-markdown、remark-gfm、rehype-raw、KaTeX |
| AI SDK 与执行后端 | Anthropic Claude Agent SDK、OpenAI Codex SDK、claude-code / kiro-cli / opencode / nga / codegenie / cursor / codex / trae-cli / magic-cli |
| 测试 | Vitest 4、Testing Library、jsdom |
| 主题 | next-themes |
文档维护
当以下内容变化时，请同步更新本 README：
package.jsonscripts、bin、files或发布流程变化- 文档中列出的环境变量变化
src/app/页面入口、API 分类或主要用户流程变化src/lib/中工作流、Spec Coding、引擎、认证、Notebook 等核心机制变化configs/、skills/或内置 Agent 能力变化- 发布版本、许可证或仓库地址变化
贡献指南
当前仓库在 README 中保留简化贡献流程；如果后续新增独立 CONTRIBUTING.md，这里应改为链接正式贡献指南。
# Fork → 创建分支 → 提交 → PR
git checkout -b feature/your-feature
git commit -m "feat: add new feature"
git push origin feature/your-featureCommit 规范遵循 Conventional Commits：feat / fix / docs / perf / refactor / test / chore
免责声明
本产品仅作为流程编排工具，不包含 AI 模型能力。用户在连接 AI 模型并将其用于特定业务场景时，需自行评估并承担包括《欧盟人工智能法案》（EU AI Act）在内的相关法律法规及合规义务。
许可证
ACEHarness 使用 Apache-2.0 with Runtime Library Exception，详见 LICENSE。