人工智能AI 应用AI Agent交互助手MCP Clients本地部署【免费下载链接】CodePilotA multi-model AI agent desktop client — connect any AI provider, extend with MCP skills, control from your phone. Built with Electron Next.js.项目地址https://gitcode.com/gh_mirrors/co0dep/CodePilot点击查看免费下载本文依据 CodePilot 仓库中的《Document System Governance / 文档体系治理》执行计划docs/exec-plans/completed/document-system-governance.md编写。它是一份已经完整落地Phase 0–5 全部完成的治理实录从两层口径的文档健康审计基线出发识别出文档量不失控、active/语义污染才是真问题随后通过四类目录语义化、批量归档搬迁、preview archive 化与结构化 lint 防线四步闭环最终让执行计划目录成为 Agent 可信的任务入口。读者读完可掌握如何用可复现脚本统计文档/代码比例如何设计active / completed / deferred / superseded四类归档语义以及如何在 lint 中实现只拦顶部 banner、不误伤正文讨论的结构化检测防止已归档计划被 AI 误读为当前任务。背景文档体系为何成为需要治理的核心基础设施在 CodePilot 中docs/exec-plans/下的执行计划文档不只是附属说明而是驱动 Codex / Claude Code 协作开发的核心基础设施——它是任务入口、历史判断、技术债务与交接记忆的共同来源。当文档语义失序时直接影响 AI 协作质量Claude Code / Codex 可能从旧的 active 文档里捡到过期任务、重复开支线或者误读当前优先级。2026-06-05 的审计发现文档量本身并不失控真正的问题是docs/exec-plans/active/的语义被污染。当时的 active 目录里混着四类性质完全不同的文档真的当前计划已经完成但未归档的发布 / 合并计划被refactor-closeout接管的 superseded 旧计划明确暂缓但仍在 active 的长期想法。治理的总体思路因此不是删文档或重写文档而是把执行计划的生命周期语义做清晰并让机器lint与 AI Agent 都遵守同一套流转规则。审计基线两层统计口径与可复现脚本审计的第一步是建立可信的统计口径。计划文档强调了一个关键坑不要用git ls-files *.md *.mdx | wc -l作为唯一口径——Git 在当前配置下会把资料/里非 ASCII 路径 quote 成 C-style 字符串普通 Node/path 统计容易把这 18 份第三方文档排除掉。统计口径分两层避免把外部参考包文档和 CodePilot 自有文档混在一起全仓跟踪文档git ls-files -z中所有.md / .mdx / .txt / .rst / .adocCodePilot 自有文档全仓跟踪文档中排除资料/下第三方参考包的文档。可复现统计脚本node NODE const cp require(child_process); const fs require(fs); const path require(path); const files cp.execFileSync(git, [ls-files, -z]).toString(utf8).split(\0).filter(Boolean); const docExt new Set([.md, .mdx, .txt, .rst, .adoc]); const codeExt new Set([.ts, .tsx, .js, .jsx, .mjs, .cjs, .css, .scss, .json, .yml, .yaml, .toml, .html]); const docs files.filter((f) docExt.has(path.extname(f).toLowerCase())); const ownedDocs docs.filter((f) !f.startsWith(资料/)); const code files.filter((f) codeExt.has(path.extname(f).toLowerCase()) !docExt.has(path.extname(f).toLowerCase())); const ownedCode code.filter((f) !f.startsWith(资料/)); const loc (f) fs.readFileSync(f, utf8).split(/\r?\n/).length; const sum (xs) xs.reduce((n, f) n loc(f), 0); console.log({ docs: docs.length, docsLoc: sum(docs), ownedDocs: ownedDocs.length, ownedDocsLoc: sum(ownedDocs), thirdPartyDocs: docs.length - ownedDocs.length, code: code.length, codeLoc: sum(code), ownedCode: ownedCode.length, ownedCodeLoc: sum(ownedCode), ownedDocCodeLocRatio: (sum(ownedDocs) / sum(ownedCode)).toFixed(3), }); NODE要点说明用git ls-files -zsplit(\0)处理路径规避非 ASCII 路径被 quote 的问题按扩展名把文档与代码/配置分开再统一排除资料/前缀第三方参考包保证两层口径可对账行数统计loc()以\r?\n分割兼容跨平台换行。审计基线数字2026-06-05指标数量全仓跟踪文档总数261全仓跟踪文档总行数62,257CodePilot 自有文档总数243CodePilot 自有文档总行数56,666第三方参考包文档18 / 5,591 行CodePilot 自有代码/配置文件总数1,119CodePilot 自有代码/配置总行数264,578自有文档 / 自有代码文件数比例0.217约 1:4.6自有文档 / 自有代码行数比例0.214约 1:4.7这份基线给出了一个可量化的结论文档与代码的比例约 1:4.61:4.7属于健康区间文档量不是治理对象语义才是。文档分布审计区域文件数行数判断docs/research/4211,693正常历史调研价值高docs/handover/419,043正常是 AI 交接主入口docs/exec-plans/completed/3712,811正常历史执行日志apps/site/content/docs/363,544正常对外文档docs/exec-plans/active/239,181 本计划需要治理docs/insights/223,288正常洞察归档docs/guardrails/131,231正常但 stub 比例仍高docs/future/81,768正常未来方向docs/preview/4602需要标 archive 语义分布表直接圈定了治理范围只有active/23 份与docs/preview/4 份需要处理其余区域保持原样——这也是不扩大治理范围原则的数据依据。当前判断四类文档的分类处理方向基于审计结果将 active 内的 23 份文档按状态归类类型数量处理方向硬过时6应更新状态并移出 activeSuperseded 但仍在 active7移到superseded/或归档并由 README 明确历史参考暂缓但仍在 active7移到deferred/保持可读但不作为当前任务入口真正当前约 3保留在 activeissue-tracker/development-harness-optimization/ 本治理计划这一分类成为后续 Phase 2 搬迁清单的直接输入。治理路线总览Phase 0–5 状态Phase内容状态用户能看到什么Phase 0审计基线 可视化看板✅ 已完成落地于ac96139有独立 HTML 看板可快速理解文档健康状态Phase 1定义目录语义 让 docs drift 认识新目录✅ 已完成ac96139active / completed / deferred / superseded四类入口已建立规则未先收紧Phase 2搬迁硬过时 / superseded / deferred 文档✅ 已完成1f7b8ea14 份 93d2f526 份active/只剩 3 个真正当前工作入口Phase 3preview 文档 archive 化✅ 已完成fc13b98旧 preview.5 说明已标历史归档不会被误读为当前测试入口Phase 4收紧结构化 lint 防线✅ 已完成5f5c08f含 self-check fixture 实测以后把 superseded / deferred banner 放进 active提交即被拦Phase 5更新索引、交接说明和可视化看板✅ 已完成本提交看板加治理已执行横幅、active 不再大片红README 目录语义 lint 看板三者一致整套治理遵循一个关键节奏先让 lint 认识新目录但不收紧规则再搬文件最后收紧结构化规则——避免文件还没搬走时制造必红窗口。Phase 0审计基线 可视化看板用户能看到什么打开一个独立 HTML 看板即可看到——当前文档数量、文档/代码比例、文档分布、过时风险、active 目录实际状态、最该处理的 6 份文档。明确不做什么不把看板混进产品代码不把看板放进正式 docs 索引不用外部依赖或构建步骤。验收方式直接打开 visual-reports/document-health-dashboard/index.html确认页面能读懂文档量不失控active 语义污染才是问题。该看板是纯静态 HTML/CSS约 900 行单文件数据来自git ls-files审计结果支持color-scheme: light dark自适应以环形图、条形图、架构列与生命周期卡片呈现文档健康状态末尾带有治理已执行横幅active 区域不再大片红色。实现路径仅交付visual-reports/document-health-dashboard/index.html无构建步骤、无外部依赖数据为审计结果静态内嵌。此部分属于 Codex / Claude Code 对齐内容用户不需要审核实现细节。Phase 1定义目录语义 让 docs drift 认识新目录用户能看到什么docs/exec-plans/变成清楚的四类入口当前 docs/exec-plans/README.md 中目录语义表即为此产物目录含义当前任务入口active/真正在推进的当前计划✅ 是completed/已完成留作历史执行日志与决策证据❌ 否deferred/用户明确暂缓、未来可能重启❌ 否superseded/被新计划接管、仅作历史参考❌ 否配套规则README 中已固化AI 只从active/领任务deferred//superseded/里的文件顶部都有Archive note说明移出原因和重启方式恢复工作由用户主动发起、再git mv回active/。明确不做什么不删除历史判断不重写大段旧计划内容不把所有旧文档一次性压缩成摘要本阶段不启用active 中禁止 superseded/deferred 顶部标记的严格规则避免文件还没搬走时制造必红窗口。验收方式docs/exec-plans/README.md的索引里能一眼看出四类目录npm run lint:docs-drift通过脚本入口见 package.json 中lint:docs-drift: node scripts/lint-docs-drift.mjs新目录还为空时 lint 也通过README 解释四类目录的语义。实现路径新建docs/exec-plans/deferred/与docs/exec-plans/superseded/更新 scripts/lint-docs-drift.mjs 使其识别四个目录源码第 14–15 行即注册了DEFERRED_DIR/SUPERSEDED_DIR本阶段只做目录索引同步和表格结构校验不全文 grepSuperseded by/本轮重构暂缓/⏸并 failREADME 表格列数校验保留。Phase 2搬迁硬过时 / superseded / deferred 文档用户能看到什么打开active/时不再看到合并前计划preview 发布前计划已被接管计划明确暂缓计划当前工作入口更干净最终 active 只剩 3 个真正当前入口。明确不做什么不改业务代码不重新评估这些计划的技术内容不把已发布历史伪装成仍需执行。验收方式以下 6 份硬过时文档不再留在active/文件处理方向active/refactor-closeout.md移到completed/作为重构收口历史active/main-merge-readiness.md移到completed/标注 main 已合并并发布active/preview-build-readiness.md移到completed/或superseded/标注 0.55.1 已发布active/preview-final-blockers.md移到completed/标注 blocker 已收口active/merge-blockers-chat-ownership-openrouter.md移到completed/标注 #37 已修active/phase-7b-macos-native-visual-profile.md默认移到completed/因为 Phase 0-2 7c 已落地Phase 3-5 用户决定不做若执行前用户重新要求 macOS 视觉继续推进则改入deferred/以下 7 份 superseded 进入superseded/agent-runtime-abstraction-revision.mdagent-sdk-0-2-111-adoption.mdagent-trust-ownership-refactor.mdchat-latency-remediation.mdcontext-storage-migration.mdopus-4-7-upgrade.mdscheduled-tasks-notifications.md以下 7 份 deferred 进入deferred/chat-run-checkpoint.mdmemory-system-v3.mdsite-and-docs.mdweixin-bridge-channel.mdqq-bridge-channel.mdunified-context-layer.mdgit-terminal-integration.mddevelopment-harness-optimization.md明确保留在 active它仍是当前协作流程优化的讨论稿不归 deferred。实现路径Codex / Claude Code 对齐用使用git mv保留历史每份文件顶部补一段Archive note包含三个要素为什么移出 active、当前替代入口是什么、若未来重启从哪里开始更新 README 索引。仓库中可见的落地产物例如 completed/refactor-closeout.md、completed/main-merge-readiness.md 等文件顶部均带有上述Archive notesuperseded/内的 opus-4-7-upgrade.md 则在标题下保留了⚠️ **Superseded by [refactor-closeout.md](https://link.gitcode.com/i/669d279c026f542f35ac5d9c6495de9f)**的接管提示——这正是 Phase 4 结构化检测所识别的 banner 形态之一。Phase 3preview 文档 archive 化用户能看到什么docs/preview/明确表示这里是历史测试包记录不是当前下载入口用户不会再把 preview.5 文档当成现在该装的版本。明确不做什么不删除 preview 历史不改 GitHub Release不重新发布包。验收方式docs/preview/README.md顶部明确写历史预览包归档internal-test-0.55.0-preview.5.md明确标为 archivebranch-preview-2026-05-31.md继续保留已废弃 / 不分发。实现路径可选新建docs/preview/archive/并git mv旧 preview 文档或保留原目录但统一加Archive标记同步更新docs/preview/README.md。最终落地采用了目录保留 archive 语义标记的方案。Phase 4收紧结构化 lint 防线用户能看到什么以后如果有人把已被接管或已暂缓的计划留在active/提交会直接失败并指出应该移到哪个目录。明确不做什么这是设计上最值得注意的部分不做全文关键词匹配不把讨论这些关键词的治理计划误判为违规不维护越来越长的 allowlist。验收方式npm run lint:docs-drift通过在临时分支 / 临时 fixture 中构造一个 active 文档文件顶部写 superseded/deferred bannerlint 会失败在 active 文档正文中讨论这些词lint 不失败。实现路径结构化检测只看文件顶部区域不看全文——读取文件前 12 行或第一个 heading 后的连续 blockquote banner仅当顶部 banner 命中以下结构信号时 fail^ .*Superseded by^ ⚠️ .*Superseded^ ⏸^ .*本轮重构暂缓正文中出现这些字符串不算违规建议给 scripts/lint-docs-drift.mjs 增加小型 fixture 测试或内置 self-check源码第 242–254 行正是内置的 banner/正文双路径自检。设计动机记录在计划文档的决策日志中Claude Code review 指出两个关键问题——第一若用全文关键词检测 active 文档本治理文档自己会触发 lint 自爆第二若先收紧 lint 再搬文件会制造中间提交必红的窗口。因此最终顺序被调整为先让 lint 认识新目录但不收紧 → 再搬文件 → 最后用结构化顶部 banner 检测收紧规则。Phase 5更新索引、交接说明和可视化看板用户能看到什么最后得到一个干净版看板——active 目录不再大片红色文档健康状态更接近真实可维护状态。明确不做什么不把看板作为永久产品功能不要求每次提交都手动更新 HTML不把这次治理扩大成全仓文档重写。验收方式npm run lint:docs-drift通过rg Superseded by|本轮重构暂缓|0.55.0-preview docs/exec-plans/active docs/preview的结果符合预期若本治理计划正文仍讨论这些词不算违规visual-reports/document-health-dashboard/index.html 更新后的结论仍能自洽docs/exec-plans/README.md是唯一可信索引。实现路径更新看板数字补充docs/exec-plans/README.md的目录语义说明如需持续使用可后续再把看板生成脚本化本轮不做。源码级解析docs-drift lint 防线由哪些检查组成治理的最终防线集中在 scripts/lint-docs-drift.mjs 单文件中除了 Phase 4 的 banner 检测它实际还承载了另外几类互补的结构化检查可以看作文档体系持续健康的完整闸门README 链接解析与索引同步第 46–109 行解析docs/exec-plans/README.md中指向active/ completed/ deferred/ superseded/的链接校验目标文件存在同时反向校验——凡是存在于四个桶中的.md文件排除各桶自己的 README必须被 README 索引到否则报not indexed错误。这保证README 是唯一可信索引。Completed → Active 引用守卫第 112–130 行已完成归档的计划不应再链接回active/下的阶段性工作文件否则读历史的人会被导回还在进行中的错误印象只允许链接到handover/、completed/同级文档或长生命周期编排器LONG_LIVED_ACTIVE当前只有issue-tracker.md。归档桶内部链接完整性第 132–164 行这是治理收尾新加入的一层——git mv保留历史但不保留相对链接目标Phase 2 搬迁后归档桶内残存 21 处失效相对链接如同目录旧同级./refactor-closeout.md指向已搬走的文件。该检查把 active/completed/deferred/superseded 四个桶内所有相对.md链接按文件自身目录解析悬空即 fail并带作用域守卫绝对路径应用路由/settings#providers、机器路径、非.md目标、http(s)/mailto/#锚点均跳过避免误报。表格结构守卫第 181–210 行索引表统一为 3 列文件 | 主题 | 状态/日期检查会拦截两行表格被并到一行||伪影与列数错误——链接存在性检查对这种合并行是无效的因为两个链接都能解析。顶部 banner 结构化检测第 219–263 行即 Phase 4 的核心topBannerRegion()取文件前 12 行 首个 heading 后连续的 blockquote 区域用 4 条锚定到^的信号正则命中即 fail正文讨论不算违规。Smoke Ledger 强制段第 265–297 行这是后续 development-harness-optimization Step 5 追加的规则——新增 active 计划必须带## Smoke Ledger段真实凭据/UI/E2E 验证结果登记在计划内而不是散落在聊天中对规则落地前已存在的 active 计划启用 grandfather clause 豁免。这些检查共同构成README 索引、目录语义、内部链接、表格形状、顶部 banner、Smoke Ledger六道防线全部由npm run lint:docs-drift一条命令触发修改 lint 脚本时还需跑npm run lint:hooks见 package.json。执行纪律与验收节奏计划文档在给 Claude Code 的执行说明一节固化了治理的执行边界这些原则对任何文档治理类任务都适用先读docs/exec-plans/README.md、本治理文件、可视化看板三份文件再动手每个 Phase 独立 commit先升级 README / docs-drift 目录语义但不要先启用active 顶部标记 fail搬迁完成后再启用结构化 lint 防线所有移动用git mv不删除历史文档不改业务代码不碰 release / tag / push每个 commit 前跑npm run lint:docs-drift改 lint 脚本时额外跑npm run lint:hooks。文档自身也附有 Smoke Ledger验证记录登记了 2026-06-05 的文档体系统计基线261 tracked docs / 243 owned docs / owned doc-code LOC ratio 0.214 / visual report generated遵循了验证结果要落在计划里的纪律。决策日志治理过程中的关键取舍2026-06-05用户要求统计文档数量、文档与代码比例、过时文档数量。Codex 审计后判断文档量本身健康主要问题是active/目录语义污染。2026-06-05用户要求生成可视化看板。Codex 将其放到visual-reports/document-health-dashboard/不混入正式 docs 索引。2026-06-05Claude Code review 指出两处关键问题——全文关键词检测会让本治理文档自身触发 lint 自爆先收紧 lint 再搬文件会制造中间提交必红的窗口。Codex 接受该 review调整为先让 lint 认识新目录但不收紧再搬文件最后用结构化顶部 banner 检测收紧规则。2026-06-05审计数字拆成两层口径——全仓跟踪文档 261排除资料/第三方参考包后CodePilot 自有文档 243。后续看板和文档同时展示这两个数。治理收尾与可复用的方法论治理完成后本治理文件自身也移出active/、归入completed/active 从 3 变为 2见文件顶部 Archive note成为规则自己先遵守规则的实例。当前docs/exec-plans/已形成稳定的四类入口 README 唯一索引 lint 六道防线的格局deferred/、superseded/内文档均带 Archive note 并指向各自的 README 说明重启/恢复方式。这套方案的可复用要点可归纳为四条先量后治用git ls-files -z的可复现脚本建立两层统计口径让文档健康有可对账的数字基线而不是凭感觉判断语义先于规则先建立四类目录语义并让 lint 认识新目录但刻意推迟收紧规则避免搬迁过程中的必红窗口结构化而非全文匹配lint 只检查文件顶部 banner 区域的结构信号^ Superseded by/⚠️ Superseded/⏸/本轮重构暂缓正文讨论这些词不违规从而让治理文档自身也能通过 lint归档要修链接git mv保留历史但不修复相对链接归档桶内部链接完整性必须纳入 lint防止查历史导航悄悄腐化。对任何以 AI AgentClaude Code / Codex 等为主要协作者的项目这套文档即任务入口的治理模式都值得直接借鉴——它解决的不是文档美观问题而是让 Agent 每次读取文档时都能准确判断这件事现在要不要做、该从哪里接手。赞分享人工智能AI 应用AI Agent交互助手MCP Clients本地部署【免费下载链接】CodePilotA multi-model AI agent desktop client — connect any AI provider, extend with MCP skills, control from your phone. Built with Electron Next.js.项目地址https://gitcode.com/gh_mirrors/co0dep/CodePilot点击查看免费下载相关推荐poi-tl结构化文档标签构建语义化的Word文档poi tl结构化文档标签构建语义化的Word文档 poi tl是一个强大的Java Word模板引擎它通过结构化文档标签SDT技术让Word文档生成模板引擎后端localizethedocs/ros2-docs-l10n文档结构优化信息组织与分类localizethedocs/ros2 docs l10n文档结构优化信息组织与分类 引言多语言文档本地化的挑战与机遇 在开源软件生态中文档的本地化L文档Gatsby 文档体系结构解析基于 Diátaxis 的四类文档模型与写作规范Gatsby 文档体系结构解析基于 Diátaxis 的四类文档模型与写作规范 本文基于 Gatsby 仓库中的 文档结构说明 https://link.gi前端静态站点Web框架上一篇深入解读 go-hclogHashiCorp 结构化键值日志库在 vcluster 中的实践下一篇PaddleSpeech s2t.training.cli 模块解析实验命令行参数解析与配置管理实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考