文档维护与证据规范
用途：维护规范。
1. 唯一正文与维护位置
| 位置 | 只维护什么 |
|---|---|
| README.md | 项目目的、阶段及最短阅读路线 |
| design/DESIGN.md | 完整自顶向下的逻辑架构、行为机制、关键取舍和开放问题概览 |
| design/TODO.md | 实施顺序、阶段交付、首批范围及验收安排；不重复设计状态或将计划计作完成证据 |
| design/docs/README.md | 阅读路线、专题职责、资料入口与术语索引 |
| 六份设计专题 | 逻辑职责、契约、场景、采用理由及证据入口；不写软件依赖、技术栈或部署正文 |
| design/docs/engineering-reference.md | 工程约束、物理部署、软件依赖、技术栈、存储与 SDK 选择；保持理由、替代项和证据边界 |
| design/docs/go-mini-integration.md | 已核对执行库事实与接入参考；不代替逻辑认知设计 |
| design/docs/research-plan.md | 唯一设计状态台账：设计约束、已定方案与用途配置 |
| design/docs/whole-system-evidence.md | 唯一实验目录、原始资料入口、一手来源及证据范围 |
| design/docs/experiments/ | 公开整理报告：实际条件、汇总统计、失败与证据边界 |
| experiments/ | 不公开的冻结条件、脚本、原始结果与失败；整理文档不改写原始证据 |
文档网站的构建与公开范围见发布说明。design/SUMMARY.md 只维护章节顺序，书稿与 HTML 由工具生成；原始测试目录和历史讨论不参与发布。
总设计以持续主体、认知组织、感知与行动为主线；对话、任务、权限及管理机制按其职责展开，不用局部实验或竞品功能清单重定义系统目标。新内容进入对应专题，不按对话轮次新增文件。跨专题变化先调整总架构，再更新各自负责的机制；其他位置保留概览和链接，避免复制详细协议、统计或进度清单。只有出现可以独立维护的新职责时才拆分专题，并同步索引。
| 跨专题主题 | 逻辑规则的维护位置 | 其他文档的分工 |
|---|---|---|
| 主体、活动与公共决定 | 主体专题维护直接认知、长期关注、Mind 私有判断、按需活动及 Self 公共整合 | 运行协议定义身份与执行契约，管理专题提供操作入口 |
| 核心与任务解耦 | 主体专题说明接续，运行协议定义生命周期、操作接纳及控制 | 管理专题展示控制结果，沙箱专题维护检查场景，工程参考说明执行装配 |
| 领域对象与受限视图 | 资料专题维护对象关系、资料内容和视图；各专题维护本领域对象与状态，运行协议维护操作接纳 | 管理专题维护领域详情，沙箱按领域装配，工程参考说明共用承载；不设万能资源实体或操作 |
| 计算节约与复用 | 资料专题维护稳定输入、有效结果及增量规则，运行协议维护提供者适配、共享执行与结算 | 工作台提供操作与用量视图，沙箱评价质量／时延／净收益，工程参考集中维护供应商与组件依据；不引入统一缓存业务实体 |
| 机密 | 管理专题维护归属、可信提交、预期接收方与授权使用；运行协议维护专用输入和外发边界 | 资料专题只维护机密与其他领域的边界，工程参考说明独立存储及 RPC 交付 |
| 热加载与动态编辑 | 运行协议维护函数编写、调用及配置生效契约；管理专题维护表单、蓝图和提交 | 工程参考维护注释及生成工具，沙箱专题维护函数评价 |
| 能力构建与实现信任 | 运行协议维护接口、产物、运行对象、准入及采用 | 主体专题说明能力缺口，沙箱专题定义试验，管理专题提供操作，工程参考说明工具链与运行环境 |
| 主动学习 | 主体专题维护学习议程与策略，运行协议维护强度及关闭行为 | 沙箱专题维护评价，管理专题维护控件，工程参考维护执行映射 |
| 人物初始化与迁移 | 主体专题维护个体形成，运行协议维护引导及兼容契约 | 管理专题维护创建与修复，沙箱专题维护检查，工程参考维护提示词交付及 API 兼容实现 |
| 客户端预制能力 | 运行协议维护可选使用、维护归属及调用作用 | 工程参考维护交付装配，管理和沙箱专题分别维护操作与评价 |
| 个体扩展状态 | 运行协议维护状态归属、结构修订及迁移 | 工程参考维护存储映射，管理专题维护可见状态 |
| 试验主体与状态导入 | 沙箱专题维护初态、激活范围、环境覆盖、生命周期及采用 | 管理专题维护页面操作；主体级测试不以完整状态复制为前提 |
以上主题涉及的 go-mini 行为统一记录在库接入参考，源码阅读与实测分别标明。方案状态统一记录在设计台账。
未来交付完整初始化提示词时，每个修订只有一份权威正文，历史正文保留。文本差异和语义迁移说明绑定相同的起止修订；迁移说明不能改变目标正文，也不能把某个个体的生成源码当作所有人物的标准实现。
2. 当前状态与证据分开
当前设计稿标明用途和必要的方案状态，不设置产品式版本号；编辑时间由版本控制记录。引用保留来源版本与修订，实验报告保留实际发生时间。
| 对象 | 标识方式 |
|---|---|
| 设计正文 | 主题与用途；区分已定目标、资料支持的采用方案和效果边界 |
| 实验与报告 | 主题名称＋稳定报告编号；输入、脚本、运行记录以原哈希识别 |
| 旧实验目录中的修订标签 | 仅为定位冻结材料保留，不用于命名当前架构或研究阶段 |
| 依赖库、论文、协议和数据 | 保留实际版本／修订／来源身份，明确其所属对象 |
已有实验的完成范围由证据索引统一维护；设计状态、配置责任及建议由决策台账维护；专题只引用与当前机制有关的证据，不包含对话进度或编辑过程。已定方案与待定细节分别标记，新方案不能直接继承其他方案的确认状态。性能或体验未知不自动变成研究任务。
区分设计目标、候选机制、固定版本库行为、设计示例、预编排流程、本地组件实测、真实模型或真人对照，以及一手资料论证。未测方案不能写成实验证伪；接口存在、结构检查通过或检索命中，也不表示完整效果通过。
引用资料记录来源、版本、支持命题、设计推论和适用边界。源码事实使用固定提交链接，上游主分支链接仅用于概览；库版本和核对范围统一在接入参考维护。
沙箱额外标明重放、重新评估或反事实，以及录制、确定计算、真实模型和模拟环境的结果来源。真实模型调用不把模拟用户反应变成真人反馈；运行事实、机械隔离、任务质量及迁移效果分别报告。
3. 结构与术语
总设计按目标 → 逻辑职责 → 概念与场景 → 子系统机制 → 逻辑取舍与验证展开。总图先呈现一级职责，再提供完整关系图；复杂机制有各自局部图，不把所有细节堆到唯一入口图中。长文保留目录、显式锚点和返回入口。设计文档只维护逻辑设计：逻辑图使用职责／概念命名，箭头表达信息、请求、结果或约束，不混入语言、库、数据库产品、SDK、进程、主机、目录或本地／远程部署选项。软件依赖图和物理部署图只放工程参考，不能以“逻辑模块不是进程”的说明保留混合图。
Self、Mind／Persona、外部 Person、对外 Role、活动、步骤、模型会话和执行上下文按总概念使用；VM／Instance／scope 等库身份在工程参考映射。自然语言“任务”按具体范围对应 Episode、Task 或 Operation，不替代带类型的控制目标；步骤、模型调用与操作接纳不是同一个边界。
统一用“沙箱”，Secret 中文统称“机密”。正文按具体对象称文档、媒体、经历、断言、Reference、程序、模型、执行环境、索引和缓存；Reference 只指可复用知识或方法说明，不代指任意引用或代码。投影是领域所有者面向当前接收者的受限视图，不是统一资源属性；对象身份与文件位置分开。读取、执行、采用、交付和清理使用具体领域语义。“资源”只在计算资源或明确的第三方协议概念中使用；go-mini 的 MRPC resource 是调用句柄，不是 TinyAGI 业务基类。独立机密沿专用授权；“程序／配置修订”不等于“产品版本”，逻辑模块不是部署进程。
当前正文写现行规则；历史语境用明确日期、报告编号或原分析定位。删除重复进度、失效推进指令和无作用的过渡说明；有证据价值的条件、来源和推导归档。文档路径、标题和编号可按内容调整；同时更新全部站内引用，不保留旧路径、重定向页或无实际内容的兼容锚点。正文和图表直接展示，不使用折叠块；以目录、标题和链接组织长文，报告中的引用也须更新。
检索按领域入口、公共接入、外部提供者和用途策略分层表述。记忆查询、资料取证、程序定位及能力发现保留各自语义，不同检索实现同级；具体产品与接口映射集中在工程参考。主体文档描述请求、结果、来源及处理范围，不展开模型内部计算与存储机制，也不将外部组件的引擎职责写成 TinyAGI 自建模块。
“试验主体”指按问题装配初态及环境、复用正式认知与运行契约的参试对象；“主体级试验”指评价完整任务或持续行为的范围。完整状态导入是有用途及兼容条件的可选方式，不使用“完整副本”泛指测试，也不把数据完整、环境就绪和评价有效混成同一结论。资料副本和备份仍按各自数据含义表述。
写作与示例
- 先说明职责，再展开约束。 每段回答一个主要问题，写清谁处理什么、依据是什么、结果交给谁。多个并列对象用表格，连续动作按发生顺序描述。
- 术语使用稳定含义。 “接纳”表示承担请求或操作责任，“采用”表示将候选用于明确范围，“交付”表示结果到达接收点。区分活动结束、任务目标达成和效果已验证，不混用“完成”。
- 用具体措辞说明范围。 例如写“仅用于已评估的任务类型”，避免只写“范围化采用”；写“展示处理状态，不展示机密原值”，避免“无原值状态”等临时组合词。
- 示例有明确情境和行为。 主体场景可从环境或自身关注开始，不要求先有用户请求；任务示例说明实际目的和结果。一个例子围绕一个主要问题展开；贯穿多个职责的场景须说明事件的先后关系。不同用户、受众或任务之间的切换必须有交代，不用堆叠边界条件代替完整过程。
- 正文面向读者，台账记录决定。 当前机制直接写现行规则；方案状态、选择理由和适用边界放在台账。不写入聊天经过、审批对话、编辑交接或内部任务安排。
- 约束强度不随润色改变。 “必须”“不得”“可以”“建议”分别表达要求、禁止、允许和建议；删减重复说明时保留触发条件、责任与适用范围。
- 格式服务于阅读。 同级标题采用一致编号，子标题层级与编号相符；长目录按主题分组。关系和反馈流程用 Mermaid，字段对照用表格；纯文本围栏保留给命令、源码和原始输出。
4. 更新顺序
先在 DESIGN.md 更新逻辑结论，并核对图、概念、场景和职责；工程映射与技术选型写入独立工程参考。通过一手资料说明采用方案、支持命题、推论、备选及适用边界，再同步专题、台账和索引。文档编辑不改变项目阶段或实验范围。资料支撑可以关闭设计决策，但不能改写实际能力或性能结论。
开展新实验前固定问题、对照、条件、指标及停止规则；运行后保留失败、未知和原始数据，并说明结果支持采用、修订还是保留未知。报告目录与方案状态分别在对应索引维护。
未来实际执行能力变化或候选采用时，按评估规格登记测试覆盖、参照／基线、评价器及门槛。未来调整测试材料或判分规则需保留原身份与理由并另行评价相关对照，不能改写旧成绩；文档补充本身不新增实验通过记录。
5. 整理检查
冻结预登记、脚本、数据和语料快照保持原样。报告可优化措辞与结构，但须保留原件，不改实验条件、统计、失败或证据范围；新增实验另建记录。整理时核对逻辑图和正文是否混入工程承载，并检查被迁移选型的理由、替代项及来源仍可追溯。核对原始证据哈希、全部站内链接、围栏、来源保留及当前／历史范围。删除过时正文时，将仍支持当前设计的资料和适用边界并入对应证据章节。
文档检查只验证这些约束；未做阅读或检索对照，就不报告可读性或检索提升的实测比例。文档变更不计作新的模型或系统实验结果。