Skip to content

知识维护规范 ​

先定位实现。行为或外部契约有变化时,更新所属专题。普通代码任务按根 AGENTS.md 工作。

单一事实位置 ​

同一契约由所属主题维护,其他页面链接过去。变更与验证记录留在 Git、CHANGELOG 或任务报告。docs/_history/ 供仓库内回溯,活动页面用行内代码指向该目录。

清晰、不冗余的主题结构 ​

只记录影响决策的理由、跨模块契约、兼容条件和现场操作。能直接从实现看出的内容,留在代码。

正文与代码的分工 ​

源码映射优先使用稳定的实现入口。代码内部默认值、调用顺序、重试和日志字段按需查看。对操作、兼容或业务判定有影响的值才写进契约。测试随实现定位。

元数据契约 ​

每个活动主题保留以下七个平面字段。字符串用 JSON 双引号,数组用单行 JSON 字符串数组。字段与非空字符串元素均须唯一,允许空数组。可保留已有 VitePress 字段。

yaml
knowledge_id: "ui.property-grid"
knowledge_type: "topic"
status: "current"
summary: "属性编辑器的选择、实例复用、失败降级和扩展验证。"
aliases: ["自定义属性编辑器", "PropertyGrid", "IPropertyEditor"]
code_paths: ["UI/ColorVision.UI/PropertyEditor"]
related: ["ui.index"]
字段契约
knowledge_id稳定且唯一,使用既有领域前缀。标题或 URL 变化时保持原 ID
knowledge_typeindex 入口、topic 能力契约、guide 工作方法、reference 定位资料、decision 设计决策
statuscurrent 当前、planned 未落地、historical 回溯。默认搜索仅 current
summary一句话说明解决的问题及重要限制
aliases真实能力、界面、配置、诊断词和关键符号。验收问题留在检索用例
code_paths仓库内已存在的源码文件或目录。使用 /、准确大小写和相对路径
related必要上下游的有效知识 ID,不引用自身、不要求递归阅读全部关联

目录路径用于匹配子路径。仓库源码用元数据或行内代码表示,网页链接留给 docs/ 内的页面。

随代码变化更新 ​

仅修正已变化的契约与源码引用。归属不清时用 impact 查候选,再核对调用者。

按变更选择验证 ​

改动本地检查
代码改动且契约、引用仍准确按代码改动选验证
仅改正文措辞、协作规则或检索工具npm run docs:check
改主题标题、元数据、增删页面或生成规则npm run docs:knowledge 后执行 npm run docs:check
改链接、章节锚点、导航、离线帮助或站点行为npm run docs:build,视觉或交互变化再用浏览器确认

docs:check 只需 Node。docs:build 另需网站依赖,并检查离线帮助、全文索引和站点链接。两者均本地执行。检索变更另复测真实问题。 检索验收

授权、保密和验证分层 ​

日志和协议示例用脱敏或合成数据。报告列明实际完成的检查及缺口,分别记录检索、源码/行为、真机和交付结果。

迁移和删除 ​

合并前迁移仍有用的前提、风险、完成判据和排障信息。合并后更新链接、related 和入口。仅在旧 URL 需要兼容时保留短跳转页,设置 redirect_from_deleted_page: true 和 search: false。有独立回溯价值的主题标为 historical。

参考依据与边界 ​

工具行为以 docs/.vitepress/scripts/ 和测试为准,AI 接手效果用实际任务独立抽样。检索验收

基于 MIT License 发布。