贡献指南

AGENTS MAINTENANCE v2.0

本指南面向 AI 智能体 与 人工协作者，给出维护知识库的标准动作。智能体进入仓库后，应先读 wiki/AGENTS.md 与组织规范。

一、任务路由

进入仓库后，先判断任务类型：

任务类型	入口	关键文档
抓取直播课 / 更新每日摘要	`python wiki/tools/update_wiki.py`	`wiki/AGENTS.md` §5
整理/重写/维护 wiki 页面	本指南 §2-§5	组织规范、实例规范
问答/复盘/交易计划/账户诊断	直接基于 wiki 内容	本体框架 + 板块档案卡 + 每日摘要

二、整理类任务 SOP

2.1 重写板块档案卡

确认该板块达到建页门槛：appearanceDays ≥ 3 && rounds ≥ 2。
参考样板 wiki/sector/光模块.md 五节结构。
数据来源：grep 全部 wiki/summaries/投顾课直播-*.md 中该板块名。
填写：
- 概览：身份层（产业群/逻辑类型/产业链/一句话）+ 认知层（当前主逻辑/逻辑演进）；新题材按"认知初始化"流程，不预设归属。
- 近三日：最近 3 个交易日的周期阶段/定性/原话；近三日无提及 → 显示休眠 + 上次活跃快照。
- 关联催化：由近及远倒序；每条带市场反应列。
- 个股热度：提及次数降序；标注首次/最近/最近角色；注意黑话清洗（如"易中天"=新易盛+中际旭创+天孚通信）。
- 相关方法论：3-5 条链接到 wiki/concept/。
同步更新 wiki/sector/_板块地图.md（如存在）。
同步 wiki/log.md 追加变更记录。

2.2 每日摘要回填

新摘要入库后，脚本/智能体需：

从新摘要提取：当日核心标签（marketState）、主线板块、点名个股、催化消息、重点机会（带模式识别）。
对每个相关板块页：
- 追加近三日状态行（淘汰最早一天）；
- 若有催化 → 追加到催化表；
- 更新个股热度计数与最近角色；
- 触发概览认知层检查（是否改变主逻辑）。
短命题材不建页；若反复出现达到门槛，走"新题材建页"流程。

2.3 新题材建页

初版只写最小已知内容：身份层标"认知初始化于 X 日，待观察"；认知层写当前主逻辑。
第 2、3 次催化出现后回填身份层产业群、逻辑类型、产业链位置。
promotedToWiki=true 前不进入板块地图。

2.4 案例回流

在方法论页（concept/）内嵌案例时，同步写入 KnowledgeCase 实例（若有实例库）。
案例注明：日期、板块、个股（可空）、槽位、老师原话、结局标签（成功/失败/待定）。
禁止在方法论页与个股页之间生成双向链接（severity: error）。

三、链接纪律 checklist

每次提交前检查：

板块页之间没有"同日活跃"导致的共现互链？
个股页（entity/）没有反向链到板块页？
板块页"相关方法论"是 3-5 条，不是几十个？
子题材已合并到父板块催化表，没有独立建页？
近三日状态窗口只保留 3 天？
新增页面已加入 wiki/index.md？
变更已记入 wiki/log.md？
情绪阶段取值在受控词汇内（启动期/发酵期/高潮期/分歧期/回流期/退潮期/休眠）？

四、Schema 校验（机器校验）

如需对实例 JSON 做合法性校验：

# 安装 ajv-cli（一次性）
npm install -g ajv-cli ajv-formats

# 校验实例数据
ajv validate \
  -s wiki/overview/schema/instance-schema.json \
  -d path/to/instances.json \
  --spec=draft7 \
  -r wiki/overview/schema/organization-schema.json \
  --all-errors

也可对规范层配置做校验：

ajv validate \
  -s wiki/overview/schema/organization-schema.json \
  -d wiki/overview/schema/organization.json \
  --spec=draft7

五、本体版本演进

schema 版本号遵循 semver：
- major：不兼容的结构性变更（如域拆分、必填字段增删）；
- minor：向后兼容的功能新增（如新增类、新增可选字段、受控词表扩充）；
- patch：文档/注释修正，不影响数据。
变更同步顺序：
1. 先改 wiki/overview/本体论框架.md（人类事实来源）；
2. 同步两个 JSON Schema + organization.json（含 changelog）；
3. 更新 docs/ 下对应规范文档；
4. 必要时更新 wiki/AGENTS.md §2 速览；
5. 记入 wiki/log.md 与 docs/changelog/。
待合并项清单维护在 wiki/overview/schema/organization.json 的 pendingMerges。

六、AI 智能体行为准则

必读规范：整理类任务动手前读 wiki/overview/本体论框架.md（或本网站规范）。
不臆造概念：情绪阶段、模式名、仓位等级必须使用受控词汇表的枚举值。
不发明链接：不因为两个板块同一天出现就互链；产业链关系写入概览文字。
案例双向同步：往方法论页加案例时考虑是否需要 KnowledgeCase 条目。
保留老师原话：状态/判断引用老师原话（带日期+说话人），不自行概括成"市场认为"。
诚实标注不确定：模式识别存疑时不标；数据噪声（黑话/误抓）显式注释。