24 lines
2.8 KiB
Markdown
24 lines
2.8 KiB
Markdown
# 人与 AI 共用的知识库
|
||
|
||
先读 README.md，按 guides/task-index.md 定位所需服务，再读 services/index.md 和 architecture/constraints.md，
|
||
并检查 verification.md 中的相关冲突。不要求把整个仓库一次性放入上下文。
|
||
|
||
- 原仓库 README 同步已按维护者要求暂缓；当前优先维护 wiki，不将源码文档同步作为其他工作的前置步骤。
|
||
- 原仓库来源的固定版本与工作区差异见 sources.md；不能把基线链接当成未提交内容已经合并的证据。
|
||
- 正式知识写给人和 AI 共同阅读；本文件只放工作规则，不另存一份服务事实。
|
||
- 以中文维护正文、commit、PR；配置键、命令和上游专有名称保留原文。
|
||
- 区分设计、配置、部署记录与现场验证。没有访问现场，不得写“运行正常”。
|
||
- 查询服务或项目状态前先问维护者：哪些工作正在动态进行、由哪个 ticket 跟踪、哪些现状尚未记录。已有明确授权的范围无需重复询问；不能从一个项目扩大到其他项目或现场查询。
|
||
- 维护者指定 ticket 为依据时，先读正文和讨论，区分已完成阶段与开放的后续范围。issue open 不等于尚未部署，README 与 ticket 不同也不能立即认定为运行异常。
|
||
- Samba AD、OCI、Proxmox 已获维护者明确指定为 IaC 优先：以 Ansible/Terraform 代码为配置依据，README 为解释。此范围内读取仓库配置无需再次询问；现场查询仍按授权范围处理，不能把代码声明当作部署验收。
|
||
- 修改前读取对应源码 README/runbook；需要现场核实时先取得维护者对范围的确认。发现差异先记录来源，不能自行把计划升级为事实。
|
||
- 新增服务同时补用途、入口、登录方式、第一次使用示例、依赖和故障入口。
|
||
- 改变行为、入口、依赖、状态或恢复方法时，在同一任务更新对应文档与服务索引。
|
||
- 跨仓库修改互相关联 commit/PR；未完成的文档同步明确记入 verification.md，不能宣称全部完成。
|
||
- 架构约束变更必须明确说明旧规则、新规则和原因，不得静默删除约束来迁就实现。
|
||
- 每项当前事实注明来源；last_verified 只在完成所述现场验证后更新，不随文字编辑刷新。
|
||
- 凭据只记录取得方式和受管位置，不复制实际密码、token、私钥、state 或含敏感值的输出。
|
||
- 不复制 apps/tailscale/helm.sh 的内容。迁移旧文档前先审查敏感内容，不能整库直接发布。
|
||
- 提交前运行 `python3 scripts/check_docs.py`；修改检查器时运行 `python3 -m unittest discover -s tests -v`。依赖与本地环境见 CONTRIBUTING.md。
|
||
- 遵守 CONTRIBUTING.md；不把临时检查日志和个人 agent memory 当成正式文档。
|