团队协作框架
团队成员与 AI 工具在同一套产品、设计、工程和发布体系下持续开发的共同规则。
本框架供团队成员与协作 AI 共同使用。每次变更都应沿着同一条路径推进：识别变更类型，找到权威来源，确认影响范围，同步文档、契约与实现，完成对应验证，并留下可继续工作的仓库状态。
本页负责说明协作方法，不替代仓库目录、技术架构、部署机制和运维基础中的具体定义。
一、使用唯一权威来源
开始修改前，必须先确认这项事实由哪里定义：
| 对象 | 权威来源 |
|---|---|
| 产品行为、业务规则、流程、权限与模块关系 | knowledge/product/ |
| 产品思想与长期原则 | knowledge/philosophy/ |
| UI 规则、组件行为与无障碍要求 | knowledge/design/ |
| 可执行视觉值与语义图标 | packages/design-tokens/ |
| 工程架构与团队协作框架 | knowledge/develop/ |
| 发布门禁与内部工程流程 | docs/ |
实现、测试、网站和生成物都不得成为第二份规范。发现来源之间不一致时，必须先确定并修正权威来源，再更新消费它的实现。
二、按变更类型判断影响
责任跟随变更，而不是跟随固定岗位。发起或实现变更的人，必须确认对应闭环已经完成。
| 变更类型 | 权威来源 | 必须同步 |
|---|---|---|
| 产品行为或业务规则 | knowledge/product/ |
产品文档、实现、行为测试 |
| UI 规则或视觉值 | knowledge/design/、Design Token |
规范、Token 或图标、实现、UI 校验 |
| Web、Gateway、SSE 或 A2UI 契约 | 双端类型与协议实现 | 双端代码、解析、契约测试 |
| 文档正文 | 对应 knowledge/<category>/ |
Markdown、链接、站点构建验证 |
| 网站呈现能力 | sites/<site>/ |
构建器、模板、响应式测试、发布测试 |
| 部署编排 | deploy/ |
配置、发布与回滚测试、线上冒烟 |
| 纯技术重构 | 对应代码模块 | 不改变产品行为的证明、最小相关测试 |
一次变更可能同时命中多行。例如修改 A2UI 组件的用户行为和视觉规则时，必须同时处理产品文档、UI 规范、双端契约、实现与对应测试。
三、保持依赖与信任边界
- 文档网站只能读取权威 Markdown 和共享 Token，不得回写正文或复制维护第二份内容。
- 页面和功能组件不得根据 Mock、混合或真实数据源模式分支；差异必须停留在 Repository 或 Provider 适配边界。
- 浏览器不得持有模型服务密钥。日志、公开文档和测试输出不得包含密钥、用户内容或内部运行时值。
- Gateway 负责可信数据、工具参数和动作授权；浏览器必须再次校验 SSE、A2UI 事件和组件目录。
- 模型输出不得绕过产品状态机、权限确认或高风险动作确认。
build/、dist/、releases/、.venv/和部署状态不是来源，不得直接修改。
四、完成同一变更闭环
如果变更影响产品行为、UI 规则或跨端契约，对应文档、类型、实现和测试必须在同一变更中完成。不得先让代码与权威来源分叉，再依赖后续任务补齐。
纯技术重构可以不修改产品文档，但必须能够通过现有行为测试证明产品结果没有变化。纯网站呈现调整可以只修改 sites/，但不得顺带改变权威正文。
五、通过对应门禁交付
- 只运行覆盖受影响范围的必要检查，并以仓库中的 CI 矩阵和发布门禁为准。
- 构建失败、契约失败或依赖 Job 被跳过时，不得将其解释为发布成功。
- 静态站点必须先生成并同步完整制品，再切换 Caddy 或新增域名。
- APP 与 Gateway 必须使用同一提交对应的制品发布；失败时恢复匹配的上一组版本。
noindex不是访问控制。所有公开网站内容都必须按任何人可直接读取来处理。
人与 AI 的共同工作方式
- 先阅读当前目录适用的
AGENTS.md和相关权威文档，再读取实现。 - 能从仓库确认的事实必须通过代码、配置或测试确认，不把猜测写成结论。
- 需要作出新规则时，先更新对应权威来源；只实现既有规则时，不创建新的说明副本。
- 交付时明确说明改变了什么、验证了什么，以及是否仍有需要后续处理的边界。
提交前五问
- 是否找到了正确的权威来源？
- 是否改变了产品行为、UI 规则或跨端契约？
- 文档、实现和测试是否形成闭环？
- 是否破坏了目录、依赖、信任或生成物边界？
- 后续成员或 AI 是否能仅凭当前仓库继续工作？