mancode

目录

• mancode 是什么？
• 为什么使用 mancode？
• 安装方法
• 使用方法
• 跨会话继续工作
• 团队协作
• 工作原理
• CLI 参考
• 隐私和安全
• 故障排查
• 常见问题
• 仍在推进

mancode 是什么？

mancode 是一个 AI 编码代理工作流调度工具。它给 agent 不同强度的工作模式： 日常任务用轻量 solo，关键任务用季后赛级别的 /man，复杂任务让教练组 subagents 负责调研、计划、实现和审查。

mancode Continuity（跨会话与团队协作运行时 负责把任务、决策和验证证据安全地 带到后续对话，并协调多人或多 Agent 的任务权威。

隐私保护与数据脱敏让你在分享日志、配置片段或客户资料前先做本地检查，生成脱敏副本； 也可分别开启共享内容门禁，减少敏感上下文暴露。

mancode 会安装三类能力：

1. 工作流权威数据：管理显式 session、TaskRef、Context Pack、workflow 和团队协调。
2. Skills / modes：提供 solo、/manba、/man、/manteam、/manps、 /mansolo 工作流模式。
3. 平台 bootstrap：把原入口接到 mancode；只有 --legacy 才安装旧 hooks。

每个受支持平台继续使用原来的 man* 入口，并通过静态 bootstrap 接入统一的 Context Pack 与 workflow authority。当 AI 编码代理写太多代码、忽略已有 UI 系统、 跳过计划，或者关键改动需要稳定工程流程时，mancode 可以作为一层本地工作流约束。

mancode 不是 Claude Code、Cursor、Codex 或 Copilot 的替代品。它是在现有 agent 上加的一层工作流：提供上下文、模式切换和审查纪律。

为什么使用 mancode？

• 减少 AI 过度设计：先复用已有代码、标准库、已安装依赖和一行修复，再考虑新增抽象。
• 分享前先保护敏感数据：在本机识别凭据和个人信息、生成脱敏副本；按需拦截敏感共享写入，或在支持的模型请求字段发往上游前替换原值。
• 在存在 UI 时匹配现有设计系统：检查项目 UI 依赖、Tailwind 配置、CSS 变量和已有组件，让 agent 复用现有颜色、字体和交互模式。
• 先把需求和计划对齐：/man 会调研项目、引导澄清会改变方案的需求、推荐可行选项并生成可确认的持久计划；计划完成后不会自动进入完整实施。
• 自由选择执行方式：计划确认后，可只保留计划、交给单个 Solo 会话实施，或继续完整 /man；受管 Solo 交接仍继承原计划、范围、审查和验收门禁。
• 保留工作流产物：调研、计划、审查报告和总结会保存到 .mancode/<namespace>/workflows/<ULID>/。
• 文档绑定的模块交付：把需求、计划、实现范围、验收标准、验证证据、review 和完成门禁绑定到同一个 workflow。
• 可恢复的交付与重构：支持 delivery record、checkpoint、reframe 和 operation recovery，避免中断后把半完成状态当成最终结果。
• 支持团队上下文：/manteam 通过 .mancode/shared/ 的类型化实体共享已确认信息。
• 维护项目术语和决策：通过用户确认的 glossary、shared decisions 和 TaskRef 减少跨会话、多代理协作中的语义漂移。
• 扫描项目健康度：mancode manps 检测陈旧 TODO、未使用依赖、风险依赖、混用图标系统和硬编码设计值。

前后对比

没有 mancode 时，像“添加退出登录按钮”这样的请求，AI 可能会新建组件、新建样式文件、 新增颜色变量。

使用 mancode 后，agent 会看到你项目里已有的 Button 组件和设计 token：

<Button variant="default" onClick={handleLogout}>
  退出登录
</Button>

默认工作流会在写代码前推动 agent 思考六个问题：

1. 这个改动解决什么问题？
2. 能否复用已有实现？
3. 最小可行改动是什么？
4. 能否不拆新系统？
5. 非平凡逻辑怎样做最小运行验证？
6. 有什么没把握的（先自查，仍不确定再问用户）？

适合什么项目？

• 正在使用 AI 编码代理的后端、Web、移动端、桌面端、CLI、库、数据或混合项目
• 希望在原 man* 命令中使用 Context Pack、skills 和显式治理的用户
• 希望 AI 代理复用已有组件和代码模式的团队
• 需要可重复 AI 辅助代码审查流程的项目
• 需要分享含客户资料、凭据或本机路径的日志、文档和配置片段，并希望先生成脱敏副本的开发者
• 希望为团队共享上下文设置敏感内容门禁的团队
• 已有 UI 组件、主题、CSS 变量或设计约定的界面项目
• 希望保留本地团队记忆、使用不发送遥测的 CLI 的团队

模型自主性与工程标准

常驻指引保留项目事实和必要边界，专业 Skill 按需提供方法；工程标准由任务原有的 requirements、plan、review、verification 和完成门禁维持。

• 普通 solo 不要求身份、session、TaskRef 或正式计划；模型选择实施方法，运行与风险相称的验证并检查实际 diff。只有需要时才增加 reviewer。
• /man 保留需求澄清、批准计划、范围、验证、审查和提交要求。已有授权仍适用时继续执行，不因关键词重复审批；新的实质决定或越界影响仍需确认。
• Man → Solo 只改变执行者，不降低交付标准。证据缺失、失败或过期时不能完成，普通 Solo 的豁免不适用于交接任务。
• finding 必须有具体证据和用户影响。修复与复查遵循任务原 policy；有新问题时补查，不为固定轮数重复审查，也不能因做过一次 review 就忽略新缺陷。
• reviewer 进程成功退出不等于 review ledger 已通过；验证命令返回 0 也不等于验收已经满足，最终状态以结构化 ledger 和 completion gate 为准。
• 交付标题、summary、commit、PR 和 handoff 应基于已接受目标、权威基线、实际读回状态和本任务 diff；无法读回的外部状态必须标记为未验证。

模型可以灵活选择工具与实现步骤，但不能自行改写已批准的目标和验收标准。

v0.6.10 更新

• 退役本地模型代理网关；旧用户按退役指南恢复客户端连接。
• 新增 macOS Keychain 支持的加密 Secrets 保险箱，通过结构化引用向已批准的本地动作注入秘密，执行结果仅返回状态。
• 修复启动前失败回执、批准摘要与临时目录清理，并加强多行终端无回显和真实宿主验收。
• Secrets 不拦截其他工具或模型流量；真实钥匙串锁定、拒绝授权等专用环境验收仍待补齐。

v0.6.9 更新

• 新增 mancode upgrade 数字菜单，一次选择更新 CLI、项目规则与 Skills，或只查看更新。
• 已初始化项目再次运行交互式 mancode init 时，可直接选择更新。
• 支持 npm 全局与普通本地安装，保留项目任务、原 policy 和托管区外内容；中断后可恢复。

v0.6.8 更新

• 完整审查与检查对齐：man 与 manba 共享基线、文件覆盖和证据复核规则；review inspect 收集实际改动，本地与 CI 使用统一检查入口。
• 可选执行门禁：新建本地 man --delivery 任务可显式声明 TDD 场景、修复预算和准确提交的 GitHub CI 条件，旧任务保留原策略。
• 有限执行与恢复：超时、取消和中断留下可恢复记录；额度耗尽后仍可查看、取消、恢复或明确追加，最后一次合法成功可以完成。
• 可信证据：Vitest 结构化 Red/Green 区分断言失败与环境错误；CI 仅接受专用观察器结果，完成前复查选定 run、attempt 和必需检查集合。
• 修复多 workflow 查询预算、同 SHA 多 run 的完成选择，以及子目录与自定义 Vitest root 的路径匹配。

新执行门禁在 Windows 上会在启动前明确报能力不可用；原 Windows CLI 与 shell 支持保留。POSIX 清理限于原进程组；门禁不拦截任意宿主文件编辑，也不把批准字段当成人类身份认证。

安装方法

状态：mancode Continuity v0.6.10。Claude Code、Cursor、ChatGPT 桌面端中的 Codex、Codex CLI、GitHub Copilot、ZCode、Kimi Code、Qoder 和 DeepSeek Harness adapter 均已接入。

需要 Node.js 22.5.0 或更高版本。原生支持 macOS、Linux、Windows CMD、 PowerShell 和 Git Bash。Git 是可选依赖：未安装时仍可初始化，只会把团队 自动检测安全降级为 solo。Claude Code hooks 由 Node 执行，不需要 Bash 或 jq。

先通过 npm 全局安装，进入你的项目目录，然后运行初始化命令：

npm install -g mancode
cd your-project
mancode init                      # 交互式选择平台
mancode init --platform cursor    # 或显式指定一个/多个平台
mancode init --platform codex,cursor
mancode init --platform all

init 会引导选择 Agent，并把检测到的 Agent 仅作为提示；不会悄悄安装全部适配器。 可以选择一个、多个或“全部平台”。Git 不是初始化前提；已有 manifest、顶层源码文件或 常见源码目录的项目可直接初始化。全新空目录会询问是否初始化为通用项目，因此用户不必 先知道 git init 或 npm init -y。之后再加入 Git 或项目源码也安全，执行 mancode refresh-project 即可刷新项目事实和已安装的静态适配器。

初始化后，继续正常使用你的编码代理。solo 默认自动生效：日常训练，零仪式感。遇到需要 计划、测试和多 agent 审查的任务时，使用 /man：季后赛，每球必争。

平台支持

• Claude Code：隐藏 bootstrap 与原 mode skills；默认不依赖 hooks
• Cursor：.cursor/rules/*.mdc bootstrap 与 .cursor/commands/ 原 mode commands
• Codex（ChatGPT 桌面端、CLI、IDE 扩展）：托管 AGENTS.md block，并在 .agents/skills/ 下提供 $man* 项目 skills
• GitHub Copilot：托管 instruction block 与 .github/prompts/ 原 mode prompts
• ZCode：托管 AGENTS.md block，并暂按 .agents/skills/ 生成 $man* skills；项目级 skill 发现和 slash commands 仍需确认 workspace 路径后再发布承诺
• Kimi Code（桌面端、CLI）：托管 AGENTS.md block，并在 .agents/skills/ 下提供 /skill:man* 项目 skills；宿主发现路径仍需真实验证
• Qoder（IDE、CLI）：托管 AGENTS.md block，并在 .qoder/commands/ 下提供 /man* 项目 commands；宿主发现路径仍需真实验证
• DeepSeek Harness：托管独立的 AGENTS.md block，并在优先级更高且与其他 agent 隔离的 .dsh/skills/ 下提供用户显式 /man* skills；官方文件发现契约已确认， GUI 发现、双窗口 session 和 subagent 传播仍需真实宿主验证
• Windsurf、Cline、Roo Code：后续计划

安装参数

mancode init --yes        # 跳过通用项目确认（CI 中仍需 --platform）
mancode init --team       # 强制启用团队模式
mancode init --no-team    # 强制禁用团队模式
mancode init --platform PLATFORMS # 一个或多个：claude-code,cursor,codex,copilot,zcode,kimi-code,qoder,dsh，或 all
mancode init --empty      # 非交互脚本中允许安全的空目录
mancode init --lang zh-CN # 显式指定初始化语言（zh-CN 或 en）
mancode init --legacy --force # 仅 legacy：重装旧 state/hook 架构
mancode init --legacy --style NAME # 仅 legacy：保存默认审美偏好
mancode refresh-project   # 后续加入 Git 或项目文件后刷新项目事实
mancode adapter status --json # 检查实际 managed content digest
mancode adapter upgrade --platform codex --dry-run # 只生成 staging 预览
mancode adapter upgrade --platform codex --confirm --operation-id <operationId> --session <id> --client <client>

一键更新（v0.6.9 起）

在项目根目录运行：

mancode upgrade

数字菜单提供：1 更新 CLI 和当前项目、2 仅更新项目规则与 Skills、3 仅更新 CLI、 4 查看更新信息、0 退出。选择后会展示版本、安装位置和文件范围，确认一次即可执行。 已初始化的项目交互运行 mancode init 也会显示更新选项。

mancode upgrade --project-only          # 用当前 CLI 更新项目，不需要联网
mancode upgrade --cli-only              # 仅更新 CLI
mancode upgrade --check --json          # 只检查，不生成项目预览
mancode upgrade --project-only --yes    # 非交互更新项目
mancode upgrade --yes                   # 非交互更新 CLI 和项目
mancode upgrade --to X.Y.Z              # 指定准确版本，拒绝降级

自动包更新支持 npm 全局安装和普通 npm 本地依赖，保留本地依赖归属与版本声明风格。 pnpm、Yarn、Bun、npm workspaces、源码 link 和临时 npx 安装会得到对应指引。 项目更新仅处理 manifest 已登记的平台，保留托管区外内容、现有任务、批准计划和 policy。 无本地身份时只需输入一次显示名；非交互使用 --name "你的名字"。已有 --session/--client 仍可显式传入，不需要手动复制新的 operation ID。

失败时输出 CLI 与项目各自的状态。修复原因后再次运行 mancode upgrade 可继续原操作； 若提示 CLI 安装结果未知，先用原包管理器修复该安装，再执行 mancode upgrade --project-only。 更新后重新打开 Agent 会话加载新入口。--json 不显示交互菜单；配合 --check 或 --yes 使用。 --lang zh-CN|en 可指定语言。

老版本首次使用： 0.6.8 及更早版本没有这个命令。先通过原包管理器 更新 CLI 一次（npm 全局安装使用 npm install -g mancode@latest；本地依赖保留原依赖归属）， 再运行 mancode upgrade。不要为了更新项目而重新初始化或删除 .mancode。

升级到 v0.6.8

先结束旧版本正在执行的 mancode 写操作，并统一升级同一工作区使用的 CLI：

npm install -g mancode@0.6.8
cd your-project
mancode adapter status --json
mancode adapter upgrade --platform codex --dry-run --json
# 审阅预览后，使用返回的 operationId 和本项目有效的 session/client
mancode adapter upgrade --platform codex --confirm \
  --operation-id <operationId> --session <id> --client codex

其他平台替换 --platform 和对应 client。更新 npm 包不会自动覆盖现有项目 Skill； 需要通过上述 adapter upgrade 同步入口。原任务继续使用原 policy，不重新创建任务来绕过门禁。 新运行时可读旧目录锁；旧 CLI 遇到新文件锁会拒绝操作，不保证新旧版本混用。 无法确认归属的历史空锁目录不会自动删除；不支持硬链接的文件系统会拒绝获取锁。

安装后创建哪些文件？

默认的 mancode init 会创建 mancode 工作流目录和平台适配文件：

.mancode/
├── schema.json
├── shared/config.json
├── shared/context/project