@leiax00/yushe-agent-kit 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (59) hide show
  1. package/.agents/dsh/plugins/yushe-user-rules/README.md +66 -0
  2. package/.agents/dsh/plugins/yushe-user-rules/cordis.patch.yml +5 -0
  3. package/.agents/dsh/plugins/yushe-user-rules/index.js +561 -0
  4. package/.agents/dsh/plugins/yushe-user-rules/package.json +9 -0
  5. package/.agents/rules/docs-management.md +16 -0
  6. package/.agents/rules/git-workflow.md +74 -0
  7. package/.agents/rules/interaction.md +35 -0
  8. package/.agents/skills/yx-api-design/SKILL.md +15 -0
  9. package/.agents/skills/yx-api-design/references/evolution.md +11 -0
  10. package/.agents/skills/yx-api-design/references/http-contract.md +33 -0
  11. package/.agents/skills/yx-api-design/references/idempotency.md +13 -0
  12. package/.agents/skills/yx-backend-architecture/SKILL.md +77 -0
  13. package/.agents/skills/yx-backend-architecture/references/common/clean-design.md +51 -0
  14. package/.agents/skills/yx-backend-architecture/references/common/common.md +31 -0
  15. package/.agents/skills/yx-backend-architecture/references/go/guide.md +9 -0
  16. package/.agents/skills/yx-backend-architecture/references/java/api-layout.md +103 -0
  17. package/.agents/skills/yx-backend-architecture/references/java/coding-style.md +36 -0
  18. package/.agents/skills/yx-backend-architecture/references/java/data-objects.md +68 -0
  19. package/.agents/skills/yx-backend-architecture/references/java/enums-and-constants.md +42 -0
  20. package/.agents/skills/yx-backend-architecture/references/java/framework-boundaries.md +25 -0
  21. package/.agents/skills/yx-backend-architecture/references/java/input-contracts.md +39 -0
  22. package/.agents/skills/yx-backend-architecture/references/java/integrations.md +54 -0
  23. package/.agents/skills/yx-backend-architecture/references/java/logging-and-audit.md +29 -0
  24. package/.agents/skills/yx-backend-architecture/references/java/mybatis-plus.md +65 -0
  25. package/.agents/skills/yx-backend-architecture/references/java/record-vs-class.md +74 -0
  26. package/.agents/skills/yx-backend-architecture/references/java/repositories-and-modules.md +95 -0
  27. package/.agents/skills/yx-backend-architecture/references/java/spring-boot.md +35 -0
  28. package/.agents/skills/yx-backend-architecture/references/java/structure.md +69 -0
  29. package/.agents/skills/yx-backend-architecture/references/java/verification.md +36 -0
  30. package/.agents/skills/yx-backend-architecture/references/python/guide.md +9 -0
  31. package/.agents/skills/yx-backend-architecture/references/typescript/guide.md +9 -0
  32. package/.agents/skills/yx-database-design/SKILL.md +16 -0
  33. package/.agents/skills/yx-database-design/references/engines.md +17 -0
  34. package/.agents/skills/yx-database-design/references/index-and-transactions.md +11 -0
  35. package/.agents/skills/yx-database-design/references/migrations.md +13 -0
  36. package/.agents/skills/yx-database-design/references/modeling.md +13 -0
  37. package/.agents/skills/yx-docs/SKILL.md +32 -0
  38. package/.agents/skills/yx-docs/references/layout.md +102 -0
  39. package/.agents/skills/yx-docs/references/module-docs.md +60 -0
  40. package/.agents/skills/yx-docs/references/notes.md +39 -0
  41. package/.agents/skills/yx-docs/references/reading-protocol.md +25 -0
  42. package/.agents/skills/yx-docs/references/releases.md +63 -0
  43. package/.agents/skills/yx-docs/references/when-to-write.md +33 -0
  44. package/.agents/skills/yx-docs/references/writing-guide.md +80 -0
  45. package/.agents/skills/yx-frontend-architecture/SKILL.md +16 -0
  46. package/.agents/skills/yx-frontend-architecture/references/frameworks.md +15 -0
  47. package/.agents/skills/yx-frontend-architecture/references/state-and-interaction.md +11 -0
  48. package/.agents/skills/yx-frontend-architecture/references/structure.md +11 -0
  49. package/LICENSE +21 -0
  50. package/README.md +76 -2
  51. package/dist/bin/yak.js +11 -0
  52. package/dist/cli/fsx.js +72 -0
  53. package/dist/cli/kit.js +47 -0
  54. package/dist/cli/main.js +132 -0
  55. package/dist/cli/targets/claude.js +47 -0
  56. package/dist/cli/targets/dsh.js +61 -0
  57. package/dist/cli/targets/registry.js +33 -0
  58. package/dist/cli/targets/types.js +1 -0
  59. package/package.json +40 -4
@@ -0,0 +1,13 @@
1
+ # 可演进迁移
2
+
3
+ 沿用 Flyway/Liquibase/Alembic/Prisma 等现有工具和编号规则;已部署迁移不改写历史,新增前向修复。不要让 ORM 自动同步作为正式环境唯一迁移机制。
4
+
5
+ 发布前检查:数据库版本、表大小、锁影响、备份恢复能力、应用兼容范围、长事务和迁移失败后的状态。在线建索引等能力需按产品/版本核实,不能只因语法支持就承诺无阻塞。
6
+
7
+ 常用扩展—迁移—收缩顺序:先增加兼容字段/表→发布可兼容新旧结构的应用→分批回填并核对→切换读取→观察→后续发布删除旧结构。字段重命名、类型收窄、NOT NULL、唯一约束须评估旧数据和滚动发布窗口。
8
+
9
+ 回填使用稳定主键范围、检查点和有限批次,设计可恢复与幂等语义;不能只使用 offset 漫扫大表。并发写入期间避免回填覆盖新值,定义双写/捕获变更和核对方案。
10
+
11
+ 区分应用回滚、结构回滚和数据恢复。破坏性 DDL 不一定可逆,down 脚本不能代替备份。清楚记录迁移失败时是可重跑、需修复状态还是需前向补救。
12
+
13
+ 在兼容数据库验证空库安装、已有数据升级、重复/脏数据、失败恢复、新旧应用兼容及关键查询计划。只生成脚本时报告未执行,而非迁移成功。
@@ -0,0 +1,13 @@
1
+ # 数据模型与约束
2
+
3
+ 先列业务实体、关系、生命周期、访问模式与数据归属。默认采用能表达业务不变量的关系模型;冗余字段需说明更新来源与一致性策略,JSON 列不替代需要约束和高频查询的结构字段。
4
+
5
+ 沿用现有命名,缺少约定时使用一致的 snake_case。主键选择考虑生成位置、索引局部性和暴露风险;主键与业务唯一键分离。金额用精确数值类型并约定币种和精度,时间明确是否表示时间点。不要用空字符串、0 和 NULL 混合表示缺失。
6
+
7
+ 在数据库能够约束的范围使用 NOT NULL、唯一键、外键和 CHECK;产品和版本是否实际执行约束需验证。外键是否启用由部署与完整性策略决定,不因“企业级”一律禁用;不用外键时明确补偿校验与孤儿记录处理。
8
+
9
+ 新业务状态默认存储显式稳定字符串业务码并定义转换,不依赖枚举序号或 Java 常量名称。业务 code 与等级 level 分离;已有数字协议、位掩码或有证据的容量约束可采用明确数字码。默认评估 VARCHAR 而非原生 ENUM 以利演进,长度、合法值约束及已有兼容性按实际需求决定。租户隔离需覆盖查询与唯一键,例如租户内唯一的业务编号应含 tenant_id;不能仅依赖应用查询条件。
10
+
11
+ 逻辑删除按恢复、审计和保留策略决定,非所有表必备。需重复复用业务键时设计活跃行唯一性;unique(key, deleted) 无法简单支持无限次删除重建。审计字段不等于完整审计日志,个人数据删除也不等于逻辑删除。
12
+
13
+ 索引、分区、归档和冷热拆分由规模与查询证据驱动,避免预先为所有表分库分表。
@@ -0,0 +1,32 @@
1
+ ---
2
+ name: yx-docs
3
+ description: 项目文档的读取与写作:分形布局约定(单服务/monorepo/功能模块)、产品/技术/使用文档、实现原理文档、决策记录(.agents/notes)、发版记录(docs/releases/)。用于查找文档、编写或整理各类文档时加载。
4
+ ---
5
+
6
+ # 文档体系
7
+
8
+ 统一原则(MUST,贯穿所有层级):
9
+
10
+ 1. **路由不堆正文**:每个 README 是索引表,不是内容堆场。
11
+ 2. **就近放置**:文档放在关注点所及的最小范围;跨模块内容上移一层。
12
+ 3. **单一权威定义**:同一事实只在一处定义,其他位置留链接。
13
+ 4. **四层记录分工**:git history 记事实、docs/releases/ 记版本对外变化、模块 history.md 记机制演进、notes 记决策理由;不相互重复。
14
+
15
+ ## 按任务加载
16
+
17
+ | 任务 | 参考 |
18
+ |---|---|
19
+ | 确定某事件发生后要写哪些文档 | [何时写文档](references/when-to-write.md) |
20
+ | 在项目中查找/理解文档 | [读取协议](references/reading-protocol.md) |
21
+ | 新建或调整仓库/服务/模块的文档结构 | [布局约定](references/layout.md) |
22
+ | 编写模块文档(实现原理、使用方法) | [模块文档指南](references/module-docs.md) |
23
+ | 编写其他任意类型文档(usage/product/tech/术语/标准/索引) | [写作指南](references/writing-guide.md) |
24
+ | 记录一个设计决策或提案 | [决策记录](references/notes.md) |
25
+ | 记录版本变更或发版 | [发版记录](references/releases.md) |
26
+
27
+ 多主题任务取并集,不默认全部加载。
28
+
29
+ ## 边界
30
+
31
+ - 放置位置、链接同步、语言风格等强制底线由 `.agents/rules/docs-management.md` 注入,本 Skill 不重复定义。
32
+ - 接口契约文档以 `yx-api-design` 维护的契约源为准,文档只是视图。
@@ -0,0 +1,102 @@
1
+ # 布局约定
2
+
3
+ 分形结构:同一套规则在仓库 → 服务 → 模块每个层级重复。约定工具无关,不绑定包管理器或语言。
4
+
5
+ ## 单服务仓库
6
+
7
+ ```text
8
+ repo/
9
+ ├── README.md # 路由入口:项目是什么 + docs/ 各目录索引 + 快速上手指引
10
+ ├── AGENTS.md # agent 工作区约定(可选,随宿主约定)
11
+ ├── .agents/
12
+ │ ├── rules/ # 强制协作规则(机制注入)
13
+ │ └── notes/ # 决策记录(见 notes.md)
14
+ └── docs/
15
+ ├── apis/ # 本服务的 OpenAPI 契约源(YAML,见下"API 契约")
16
+ ├── usage/ # 使用说明书(目录,见下)
17
+ ├── product/ # 产品文档(目录,见下)
18
+ ├── tech/ # 技术文档(目录,见下)
19
+ ├── releases/ # 发版记录:一个版本一个文件(见 releases.md)
20
+ │ ├── unreleased.md # 未发布变更的累积区
21
+ │ └── v1.2.0.md # 已定稿的版本记录,冻结不改
22
+ ├── standards/ # 定义的标准:团队内部规范全文(见下)
23
+ ├── references/ # 外部引用资料索引(见下)
24
+ ├── glossary.md # 名词解释:跨服务术语的唯一权威定义源
25
+ ├── iterations/ # 迭代记录:一个迭代一个目录(见 writing-guide.md 模板)
26
+ ├── AUTHORING.md # 贡献:怎么改这个仓库
27
+ └── modules/ # 功能模块文档(见 module-docs.md)
28
+ ```
29
+
30
+ ### docs/ 下的主题目录
31
+
32
+ 每个目录一个主题域,内含多个专题文件;服务 README 的索引表路由到文件级:
33
+
34
+ - **`usage/`** — 使用说明书,面向使用者/运维:`quickstart.md`(快速上手)、`configuration.md`(配置说明)、`troubleshooting.md`(排障)等,按需增拆。
35
+ - **`product/`** — 产品文档,面向产品视角:产品定义说明、功能说明、设计稿。设计稿等二进制资源不入 docs/,product/ 内放**索引页**(链接到 Figma/资产库/`assets/`),关键信息 MUST NOT 只存在于图片里——图中承载的结论要用文字在 md 中复述。
36
+ - **`tech/`** — 技术文档,面向技术综述:技术栈清单及理由摘要、系统架构说明、部署拓扑。**选型/取舍的完整论证以 `.agents/notes/` 为权威**,tech/ 只作综述视图并链接过去,MUST NOT 双写论证。
37
+ - **`standards/`** — 团队定义的标准全文(编码规范、流程规范、质量标准)。与 `.agents/rules/` 分工:rules 是机制注入的强制约束,standards 是供查阅的标准全文;某条标准需要强制执行时提炼成 rule 并链接回全文。
38
+ - **`references/`** — 外部引用资料索引:第三方官方文档、规范原文、内部 wiki 等。只做索引页(每条注明覆盖什么、何时该查),MUST NOT 复制外部内容入库——复制即开始腐化;链接失效时标注而非静默替换。
39
+ - **`glossary.md`** — 跨服务术语表,术语的唯一权威定义源。模块内部概念仍归模块 design.md 的概念小节,glossary 只收跨模块使用的词并链接到定义处;发现同一词多处解释时收敛到 glossary。
40
+
41
+ ### API 契约(apis/)
42
+
43
+ 后端服务的接口契约用 **OpenAPI YAML** 作为源文件(不是 md),归实现它的服务所有:
44
+
45
+ 1. spec 跟服务走:单服务仓库放 `docs/apis/`,monorepo 放 `docs/services/<service>/apis/`;文件名即服务名(`order-service.yaml`),一个服务多个 API 面(对外/对内)时一面上一个文件。
46
+ 2. spec 是唯一契约源:文档中所有接口的 md 描述都只是视图,MUST NOT 与 spec 双写;契约细节以 spec 为准(与 `yx-api-design` 的原则一致,契约编写规范也由该 Skill 承载)。
47
+ 3. 跨服务发现:L0 `docs/tech/` 只放索引表(服务 → spec 路径 → 一句话职责);需要聚合视图(如网关合并全量 spec)时生成产物,不手工维护。
48
+ 4. 版本联动:spec 的破坏性变更 MUST 同步记入该服务 `releases/unreleased.md`。
49
+
50
+ ## Monorepo(可混合多语言)
51
+
52
+ 整个仓库**只设一个根 `docs/`**,服务维度在 docs 内部体现为一级 `services/` 目录;代码按角色分组(apps/packages),文档统一入口。
53
+
54
+ ```text
55
+ mono/
56
+ ├── README.md / AGENTS.md # L0:仓库地图 + 各单元一句话 + 指向 docs/ 索引
57
+ ├── .agents/notes/ # 全局决策记录
58
+ ├── docs/ # ★ 仓库唯一的文档根
59
+ │ ├── product/ # 产品级:产品定义、功能地图、设计稿索引(唯一产品定义源)
60
+ │ ├── tech/ # 跨服务技术:总体架构、服务间契约视图、技术栈综述
61
+ │ ├── standards/ # 团队标准全文
62
+ │ ├── references/ # 外部引用资料索引
63
+ │ ├── glossary.md # 跨服务术语表(唯一权威定义源)
64
+ │ ├── iterations/ # 迭代记录:一个迭代一个目录(见 writing-guide.md 模板)
65
+ │ │ └── 2026-W46/ # {plan.md, review.md},结束后冻结
66
+ │ ├── services/ # 各服务专属文档,目录名与代码单元名对应
67
+ │ │ └── <service>/ # 结构与单服务的 docs/ 相同(分形递归)
68
+ │ │ ├── apis/ # 该服务的 OpenAPI 契约源(YAML,见下"API 契约")
69
+ │ │ ├── usage/ # 该服务的运维/配置/排障
70
+ │ │ ├── tech/ # 该服务的技术实现
71
+ │ │ ├── releases/ # 该服务的发版记录
72
+ │ │ └── modules/ # 该服务的功能模块文档
73
+ │ └── AUTHORING.md # 贡献:怎么改这个仓库
74
+ ├── apps/ # 可部署单元(前端应用、后端服务),按角色不按语言
75
+ │ └── order-service/
76
+ └── packages/ # 共享库(组件库、util、SDK)
77
+ └── ui-components/
78
+ ```
79
+
80
+ 规则:
81
+
82
+ - **归属跟着描述对象的边界走**:产品级 → `docs/product/`;跨服务技术 → `docs/tech/`;单服务内容 → `docs/services/<service>/` 下细分。
83
+ - `docs/services/<service>/` 的内部结构与单服务仓库的 `docs/` 完全一致——同一套分形规则递归,不引入新概念。
84
+ - 服务目录名 MUST 与代码单元名(apps/packages 下的目录名)一致,靠命名对应而非路径映射。
85
+ - 跨单元契约(如前端调后端的 API)放 `docs/tech/`,以契约源为准。
86
+ - 每个可发布单元独立维护自己的 `releases/`(在 `docs/services/<service>/releases/`);根级 MUST NOT 放汇总——跨单元发版说明按需聚合生成,常驻汇总会让无关变更互相冲突。
87
+ - 独立发布的 package(如组件库、SDK)如果文档量大,同样走 `docs/services/<package>/`(目录名与 packages/ 下一致);量小时先并入 `docs/tech/` 的共享库说明,不预建空结构。
88
+
89
+ ## 模块目录(docs/modules/)
90
+
91
+ 模块是**功能视角**的切分,不要求与代码包一一对应;一个模块可对应一组包、一个域或一个子服务。
92
+
93
+ ```text
94
+ docs/modules/<module>/
95
+ ├── README.md # 路由:职责、主要入口、依赖领域、指向下列文档
96
+ ├── usage.md # 使用方法(外部有消费者时才需要)
97
+ ├── design.md # 实现原理(核心文档)
98
+ └── history.md # 实现演进史(见 module-docs.md)
99
+ ```
100
+
101
+ - 模块与代码的关联用**主要入口和依赖领域**表达(见 module-docs.md 模板),MUST NOT 维护文件路径映射表——路径级映射维护成本远超收益,且 git history 已是路径事实的权威。
102
+ - 模块数量增长后,服务 README 的索引表按域分组呈现。
@@ -0,0 +1,60 @@
1
+ # 模块文档指南
2
+
3
+ 模块是功能视角的切分,一个模块目录承载该功能块的实现原理。核心目标:**记录代码装不下的机制与取舍**,不复述代码。
4
+
5
+ ## 目录与文件
6
+
7
+ ```text
8
+ docs/modules/<module>/
9
+ ├── README.md # 路由,≤30 行
10
+ ├── usage.md # 使用方法:外部有消费者时才建
11
+ ├── design.md # 实现原理:核心文档,模块存在即 SHOULD 有
12
+ └── history.md # 实现演进史:模块存在即 SHOULD 有
13
+ ```
14
+
15
+ 领域概念(术语、不变量、状态机)并入 design.md 的固定小节;只有概念多到淹没原理叙述时才拆 `concepts.md`。
16
+
17
+ ## README.md 模板(路由)
18
+
19
+ ```markdown
20
+ # <模块名>
21
+
22
+ <职责一句话>
23
+
24
+ - 主要入口:<类/接口/函数名,不写文件路径>
25
+ - 依赖领域:<模块/领域名列表>
26
+ - 文档:[实现原理](design.md) · [使用方法](usage.md)
27
+ - 最后核实:yyyy-mm-dd(按 <项目主框架版本> 核实)
28
+ ```
29
+
30
+ ## design.md 结构(实现原理为核心)
31
+
32
+ 1. **概述**:解决什么问题,边界在哪。
33
+ 2. **机制**:核心流程怎么运转;数据流/状态流转用文字或 Mermaid,不用截图承载关键信息。
34
+ 3. **关键取舍**:做了什么选择、放弃了什么、为什么;理由链指向 `.agents/notes/` 的对应记录,不在此重复长篇论证。
35
+ 4. **领域概念**:术语表、不变量、状态机(简小时一节带过)。
36
+ 5. **已知边界与坑**:并发约束、性能特征、易错点。
37
+
38
+ ## history.md 模板(实现演进史)
39
+
40
+ 记录**模块机制的演进**,不是发版清单(那是服务级 docs/releases/ 的事),也不是决策论证(那是 notes 的事)——它是模块粒度的"何时、变了什么、一句为什么":
41
+
42
+ ```markdown
43
+ # 实现演进
44
+
45
+ - 2026-11-18 引入状态机替代散落的 if/else 收敛订单状态流转(背景见 notes/<链接>)
46
+ - 2026-09-02 库存扣减改为乐观锁,悲观锁在高并发下死锁频发
47
+ ```
48
+
49
+ 规则:
50
+
51
+ 1. 机制发生实质变化(换了做法、加了关键约束、拆了结构)时,同一变更追加一条;纯字段增删、typo 不记。
52
+ 2. 每条一行:日期 + 变化 + 一句话理由;理由需要展开的链接到 `.agents/notes/`,模块内的小决策理由写在条目里即可,不必都开 note。
53
+ 3. 只追加不修改;写错了下一条更正,不改历史条目。
54
+
55
+ ## 写作约束
56
+
57
+ - 路径引用控制在"主要入口 + 依赖领域"粒度:写类名、接口名、模块名;MUST NOT 维护文件路径映射表——git history 是路径事实的权威,路径级映射是维护地狱。
58
+ - 引用代码用名称(`OrderAppService`)而非路径;读者用 IDE/搜索定位。
59
+ - 修改模块行为后,同一变更中同步更新 design.md 的机制描述;只改事实(名称、结构),不改写历史决策。
60
+ - 中文为主,技术名词保留英文;表格优于长段落。
@@ -0,0 +1,39 @@
1
+ # 决策记录(.agents/notes/)
2
+
3
+ 记录**代码和常规文档装不下的"为什么"**:设计决策、被拒绝的方案、取舍理由。参考 DSH 的 Agent Notes 体系,做通用简化——无脚本门控,靠约定执行。
4
+
5
+ **定位边界**:notes 是决策记录,不是 agent 执行日志——会话过程记录是临时产物,不落库。层级分工:跨模块/架构级决策记 notes;模块内实现演进记模块 `history.md`(见 module-docs.md,小决策理由直接写在条目里,不强制开 note)。
6
+
7
+ ## 与分支/快速迭代的配合
8
+
9
+ notes 的粒度是**一次变更一条记录**,与特性分支一一对应,适合比迭代更细的快速迭代节奏:
10
+
11
+ 1. 开特性分支时开一条 `proposed/` note:先写清背景、方案、替代方案、验收标准,再动手实现。
12
+ 2. 实现过程中随认知更新 note 内容(方案调整、新发现的约束)。
13
+ 3. 合入时一次完成:note 移入 `implemented/`(事实与代码同步);涉及模块的 `history.md` 追加一条演进;对外可感知的变化写入 `releases/unreleased.md`。
14
+ 4. 分支删除,note 留存——分支是过程,note 是记忆。
15
+
16
+ 一次变更 = 分支(过程)+ note(为什么)+ history(模块演进)+ unreleased(对外变化),四层各记各的。`iterations/` 目录是可选的时间盒记录,仅当团队真的做排期与回顾时使用。
17
+
18
+ ## 布局与命名
19
+
20
+ 路径编码两个轴:`{生命周期}/{class}/yyyy-mm-dd-主题.md`。
21
+
22
+ - **生命周期**(顶层目录,随状态移动):
23
+ - `proposed/` — 尚未实现的提案,评审中。
24
+ - `implemented/` — 决策已落地。随代码演进**保持事实同步**:代码改名、移动、改关键默认值时,同一变更更新记录中的事实(只改事实,不改写决策本身)。
25
+ - `rejected/` — 被否决的方案。仅在"其理由能防止一个有诱惑力的重复犯错"时保留,否则删除。
26
+ - **class**(子目录,开放集合,按项目需要增删):`feature` / `architecture` / `simplification` / `bug-fix` 等功能视角分类。
27
+ - 文件名日期 = 首次提出日期(按 git history)。
28
+
29
+ ## 写作规则
30
+
31
+ 1. 每篇记录:背景与问题、决策与理由、放弃的替代方案、后果、需要的验证。
32
+ 2. 互引用相对 Markdown 链接,MUST NOT 用裸编号——链接可机械校验且在目录间移动后仍有效。
33
+ 3. **不设中心 INDEX.md**:目录树即清单;中心索引会让无关变更在同一生成文件上冲突。
34
+ 4. **替代检查**:写新记录前检索既有记录,完全取代的移入对应生命周期并互相链接;部分取代的双向链接后都保持活跃。
35
+ 5. `archived/`(可选):仅存历史价值大于指引价值的落地记录,冻结不改、不作当前依据。
36
+
37
+ ## 与其他载体的分工
38
+
39
+ git history 记事实,docs/releases/ 记版本对外变化,模块 history.md 记机制演进,notes 记理由——四层不重复(统一定义见 releases.md)。模块 design.md 的"关键取舍"只留结论和指向 notes 的链接。
@@ -0,0 +1,25 @@
1
+ # 读取协议
2
+
3
+ 在项目中查找文档时的确定性流程,不靠自由发挥。
4
+
5
+ ## 进入仓库
6
+
7
+ 1. 先读根 README 的索引表定位目标;存在 AGENTS.md 一并读(宿主通常已注入)。
8
+ 2. monorepo:仓库只有一个根 `docs/`——产品级查 `docs/product/`,跨服务技术查 `docs/tech/`,单服务内容查 `docs/services/<service>/`(内部结构与单服务 docs/ 相同)。服务定位不清时先看根 README 的仓库地图。
9
+ 3. 找模块文档:服务 README 索引 → `docs/modules/<module>/README.md` → 专题文件。
10
+
11
+ ## 判断文档可信度
12
+
13
+ 4. 读每篇先看头部元信息(见 module-docs.md 模板):受众不符或标注"以代码/契约源为准"的,转去读代码或契约源。
14
+ 5. 文档描述与代码冲突时:代码和契约源是事实,文档是视图;以代码为准并向用户报告文档过时,MUST NOT 按过时文档"纠正"代码。
15
+ 6. 注意文档中的过时标注(`> ⚠️ 过时`):仅作历史上下文,不作为当前依据。
16
+
17
+ ## 恢复决策背景
18
+
19
+ 7. 想知道"为什么这样设计/为什么不用方案 B":查 `.agents/notes/`(先 implemented/,再 rejected/——被拒绝的方案尤其防止重复踩坑),见 notes.md。
20
+ 8. 想知道"版本间变了什么":读 `docs/releases/`(先 `unreleased.md`,再具体版本文件);模块机制的演进看模块 `history.md`;精确到 commit 的事实查 git history。
21
+
22
+ ## 效率约束
23
+
24
+ 9. 遵循条件加载:索引表命中哪个文档读哪个,不因"顺便"全量通读。
25
+ 10. 已读且未变化的文档不重复读取。
@@ -0,0 +1,63 @@
1
+ # 发版记录(releases/)
2
+
3
+ 一个版本一个文件,替代单文件滚动 CHANGELOG——版本记录天然独立,目录形态避免无关变更互相冲突,且单版本可被直接链接(`docs/releases/v1.2.0.md`)。
4
+
5
+ ## 文件与格式
6
+
7
+ ```text
8
+ docs/releases/
9
+ ├── unreleased.md # 未发布变更的累积区,唯一活跃文件
10
+ └── v1.2.0.md # 已定稿的版本记录,冻结不改
11
+ ```
12
+
13
+ `unreleased.md` 与版本文件同格式:
14
+
15
+ ```markdown
16
+ # v1.2.0(2026-11-18)
17
+
18
+ ## Added
19
+ - <新能力,一句话>
20
+
21
+ ## Changed
22
+ - <行为/契约变化,注明影响>
23
+
24
+ ## Fixed
25
+ - <修复的问题>
26
+ ```
27
+
28
+ 分类沿用 Keep a Changelog:`Added` / `Changed` / `Deprecated` / `Removed` / `Fixed` / `Security`。
29
+
30
+ ## 流程
31
+
32
+ 1. 交付一个可感知变化时,同一变更追加条目到 `unreleased.md`。
33
+ 2. 发版时:将 `unreleased.md` 定稿为 `v<版本>.md`(填版本号和日期),重建空 `unreleased.md`。
34
+ 3. 已定稿的版本文件 MUST NOT 修改;写错在下个版本更正。
35
+
36
+ ## 如何构建一份版本记录
37
+
38
+ 版本记录的主要来源是**交付时同步写入**的 `unreleased.md`;发版时按下述顺序汇集、校验、补全,不靠临场回忆:
39
+
40
+ 1. **读 `docs/releases/unreleased.md`**——主来源。四层分工要求合入可感知变化时同步写条目,发版时它应当已基本成形。
41
+ 2. **校验遗漏:`git log <上一版本标记>..HEAD`**——对照提交记录(尤其 `feat`/`fix`/带破坏性说明的提交)逐条核对是否都已体现在 unreleased;漏记的补上。上一版本标记取上一版本文件内的日期对应的 tag/提交,没有 tag 时用上一版本文件的定稿日期。
42
+ 3. **核对模块演进:本期各模块 `history.md` 新增条目**——判断机制演进是否产生对外可感知影响;有则升格为版本条目,纯内部演进不进版本记录。
43
+ 4. **核对决策:本期 `implemented/` 新增与更新的 note**——其中标注破坏性变更/迁移要点的,提炼进版本记录并链接 note。
44
+ 5. **核对契约:`apis/` 的 spec 变更**——接口的增删改与废弃 MUST 有对应条目。
45
+ 6. **定版本号**:有破坏性变更 → major(0.x 阶段可按 minor 处理并注明);仅新能力 → minor;仅修复 → patch。
46
+ 7. **定稿**:unreleased.md 重命名为 `v<版本>.md`(填日期),重建空 unreleased.md;如仓库用 tag,同步打 tag。
47
+
48
+ 范围边界:一次发版覆盖该服务自上一版本以来的全部合入;monorepo 中各服务独立执行上述流程,各自定稿。
49
+
50
+ ## 记录规则
51
+
52
+ 1. **只记用户可感知或影响契约的变化**(新能力、行为变更、破坏性变更、依赖要求变化);内部重构、无感知修复不记——那是 git history 的事。
53
+ 2. 破坏性变更 MUST 显式标注并写迁移要点。
54
+ 3. 模块机制的演进记模块 `history.md`(见 module-docs.md),不重复进版本记录;版本记录只反映对外可感知面。
55
+
56
+ ## 四层分工(统一定义,他处只引用)
57
+
58
+ | 层 | 载体 | 记什么 | 何时写 |
59
+ |---|---|---|---|
60
+ | 事实 | git history | 每次改动的精确内容 | 提交即产生 |
61
+ | 版本 | docs/releases/ | 版本级、人可读的对外变化 | 交付可感知变化时 |
62
+ | 演进 | docs/modules/*/history.md | 模块机制的演进 | 模块机制实质变化时 |
63
+ | 理由 | .agents/notes/ | 决策与取舍 | 决策发生时 |
@@ -0,0 +1,33 @@
1
+ # 何时写文档
2
+
3
+ 写文档的触发时机对照表:事件发生时按表执行,不在表中事件不强制写。具体格式见 writing-guide.md / module-docs.md / notes.md / releases.md。
4
+
5
+ ## 事件 → 动作对照
6
+
7
+ | 事件 | 要写的文档 |
8
+ |---|---|
9
+ | 开特性分支、开始一次变更 | 开 `proposed/` note(背景/方案/替代方案/验收,**动手前**写) |
10
+ | 实现中方案调整、发现新约束 | 更新对应 note 的内容 |
11
+ | 合入代码 | ① note 移入 `implemented/`(事实同步)② 模块机制实质变化 → 该模块 `history.md` 追加一条 ③ 对外可感知 → `releases/unreleased.md` 条目 ④ 模块机制变化 → `design.md` 机制描述同步更新 |
12
+ | 接口增删改废 | 更新本服务 `apis/` 的 spec;破坏性变更同步 unreleased 条目与迁移要点 |
13
+ | 出现跨模块使用的新术语 | `glossary.md` 加词条(模块内部概念进模块 design.md,不进 glossary) |
14
+ | 做了技术选型/架构决策 | 开 note 记录论证;落地后 `tech/stack.md` 综述表更新并链接 note |
15
+ | 产品功能定义或边界变化 | 更新 `product/definition.md` 功能地图(含负面清单);迭代模式下调期结束时更新 |
16
+ | 新建功能模块 | 建模块目录:README + design.md + history.md(首条记录初始设计) |
17
+ | 新建服务/可发布单元 | 建 `docs/services/<name>/` 骨架;根 README 仓库地图加一行;`docs/tech/` 架构文档加组件 |
18
+ | 发版 | 按 releases.md 的汇集流程定稿(读 unreleased → git log → history → notes → spec 校验) |
19
+ | 移动/重命名文档 | 同步更新所有引用链接(规则已强制) |
20
+ | 发现文档与代码冲突 | 以代码为准,同一变更修正文档;无法立即核实的标注"待核实" |
21
+ | 做时间盒排期与回顾(若采用迭代) | `iterations/<编号>/` 的 plan.md / review.md |
22
+
23
+ ## 什么时候不写
24
+
25
+ - **不预建空结构**:没有内容的目录/文件不创建(空的 usage/、只有一个词条的 glossary 都等有实料再建)。
26
+ - **内部重构、无对外感知的变化**不写 unreleased 条目——git history 已记录;模块机制有实质变化才写 history.md。
27
+ - **临时性内容不落库**:会话过程、调试笔记、TODO 清单、进度汇报不属于文档。
28
+ - **不重复记录**:该记在代码注释/git message 里的不搬进文档;表内未触发的事件不"顺手"写。
29
+ - **不确定受众的文档不写**:说不出谁在何时会读,就先不写。
30
+
31
+ ## 原则
32
+
33
+ 文档与变更**同生**(同一提交/同一合入完成),不发版后补写——补写的文档必然失真。审查一次变更时,上表命中的动作未完成视为变更未完成。
@@ -0,0 +1,80 @@
1
+ # 写作指南
2
+
3
+ 各类文档的通用写作规范与模板。模块文档另有专属模板(见 module-docs.md),与其冲突时以专属模板为准。
4
+
5
+ ## 通用原则
6
+
7
+ 1. **受众先行**:动笔前先确定写给谁(使用者/运维/产品/新成员/agent);受众不明的内容先别写。
8
+ 2. **渐进披露**:第一段给出"这是什么、何时该读"的摘要;细节往后放。标题即锚点,`##` 小节可被直接链接。
9
+ 3. **结论用文字,不用截图承载**:图中结论必须文字复述;流程/结构优先 Mermaid,其次表格,最后长段落。
10
+ 4. **可核实性**:涉及版本敏感行为(框架 API、插件配置)标注核实日期与依据版本;未验证的写"待验证",不写成事实。
11
+ 5. **中文为主**,技术名词、命令、代码保留英文。
12
+ 6. **不复制外部内容**:引用外部资料链接到 `references/` 的索引条目,正文只写结论与出处。
13
+
14
+ ## 头部元信息
15
+
16
+ 每篇正文文档(README 索引文件除外)开头用一行引用块声明元信息:
17
+
18
+ ```markdown
19
+ # <标题>
20
+
21
+ > 受众:<使用者/维护者/产品> | 范围:<覆盖什么> | 最后核实:yyyy-mm-dd(按 <版本/依据>)
22
+ ```
23
+
24
+ 内容实质变化时更新"最后核实";只改笔误不动。
25
+
26
+ ## 各类文档模板
27
+
28
+ ### usage/(使用说明书)
29
+
30
+ - `quickstart.md`:目标(10 分钟内跑起来)→ 前置条件 → 步骤(可复制的命令块)→ 预期结果 → 下一步去哪。
31
+ - `configuration.md`:配置项表(项/类型/默认值/说明/是否必填),按作用分组;配置变更的影响与风险随条目注明。
32
+ - `troubleshooting.md`:症状 → 原因 → 处置,每条一个 `##` 小节;症状写用户实际看到的现象,不写内部错误码反推。
33
+
34
+ ### product/(产品文档)
35
+
36
+ - `definition.md`:产品定位、目标用户与场景、功能地图(功能域 → 一句话职责 → 负责服务)、明确不做什么(负面清单)。
37
+ - 功能说明类:用户故事式(谁在什么场景做什么),不写实现;功能与服务的对应关系链接 tech/ 的架构文档。
38
+ - 设计稿索引:条目 = 名称 + 链接 + 覆盖范围 + 状态(草案/定稿/已实现);结论性内容文字复述。
39
+
40
+ ### tech/(技术文档)
41
+
42
+ - `stack.md`:技术栈表(领域/选型/版本/一句话理由摘要);完整论证链接 `.agents/notes/`。
43
+ - `architecture.md`:系统组成图(Mermaid)+ 每个组件一段(职责、依赖、部署形态);数据流与关键链路单独成节。
44
+ - 写现状,不写历史(历史归 history/notes);写"是什么、为什么这样",不写操作步骤(那是 usage 的事)。
45
+
46
+ ### glossary.md(术语表)
47
+
48
+ - 按词条字母/拼音排序,每条:`## <术语>`(英文标识 `identifier`)——定义一两句 + 首次出现的背景/出处链接。
49
+ - 一个词只在此定义一次;模块内部概念不进 glossary,在模块 design.md 定义后由 glossary 链接。
50
+
51
+ ### standards/(标准全文)
52
+
53
+ - 标准文档按主题一文件;条目带 RFC 2119 强度(MUST/SHOULD/MAY),与本 kit 语义一致。
54
+ - 需要强制执行的标准在 `.agents/rules/` 提炼条目并链接回本文。
55
+ - 标明来源:团队自定(共识日期)/ 参考的外部规范(链接,不复制原文)。
56
+
57
+ ### references/(外部引用索引)
58
+
59
+ - 每条:名称 + 链接 + 覆盖什么 + 何时该查;失效链接标注"已失效(日期)",不静默删除或替换。
60
+
61
+ ### iterations/(迭代记录)
62
+
63
+ 迭代是产品级时间盒,跨服务,放根 `docs/iterations/<编号>/`(编号用团队习惯:`2026-W46`、`R12` 等)。一个迭代一个目录,结束后冻结不改:
64
+
65
+ - `plan.md`:目标(为什么做这几件事)→ 范围(功能点列表,链接 product/ 对应条目)→ 明确不做的 → 验收标准。
66
+ - `review.md`:交付结果对照计划(完成/移出/取消及原因)→ 关键数据 → 复盘发现;改进动作的制度性结论开 note(决策记录),不堆在 review 里。
67
+
68
+ 分工:iteration 记"这期做了什么",产品能力的长期事实归 product/——迭代完成时更新功能地图;服务侧不建 iteration 目录,具体变更看各服务 releases/。
69
+
70
+ ### README.md(各级索引)
71
+
72
+ - 只做路由:根 README = 项目一句话 + docs/ 目录索引表(目录/文件 → 一句话 → 何时读)+ 快速上手链接;服务 README 同构。
73
+ - 索引表是唯一内容;服务 README 另加一句"本服务在产品中的定位"。
74
+ - 不放正文段落超过三行。
75
+
76
+ ## 写作流程
77
+
78
+ 1. 先确认类型与受众 → 找同类型既有文档沿用其结构。
79
+ 2. 写完自查:新读者能否在 30 秒内判断"这篇是否该读";agent 能否仅凭标题和小节定位信息。
80
+ 3. 提交前核对:链接有效、引用路径相对化、元信息已更新。
@@ -0,0 +1,16 @@
1
+ ---
2
+ name: yx-frontend-architecture
3
+ description: 设计、实现或评审前端业务模块、组件边界、状态、表单和异步交互;适用于 React/Vue 与 TypeScript 项目,接口契约和数据库设计由对应 Skill 负责。
4
+ ---
5
+
6
+ # 前端架构
7
+
8
+ 先检查项目规则、package.json、路由、组件库、状态与请求工具和同类页面。沿用已采用的框架,不为采用本规范引入新的 UI 或状态库。
9
+
10
+ 1. 读取 [模块与数据边界](references/structure.md),按当前任务选择页面、业务组件和共享组件的边界。
11
+ 2. 涉及请求、缓存、表单或并发交互时读取 [状态与交互](references/state-and-interaction.md)。
12
+ 3. 根据实际框架读取 [React/Vue 适配](references/frameworks.md) 中对应部分。
13
+ 4. 新增或改变接口契约时显式加载 `yx-api-design`;不可用时沿用已存在契约并报告缺失,不假定依赖自动加载。
14
+ 5. 验证用户可观察的成功、空态、加载、失败和无权限路径;涉及交互时检查键盘操作与焦点。
15
+
16
+ 交付说明修改的用户流程、组件/状态归属、契约变化及验证结果。不要只为目录整齐迁移未涉及页面。
@@ -0,0 +1,15 @@
1
+ # React / Vue 适配
2
+
3
+ 只阅读项目对应部分;具体 API 以项目锁定版本为准。
4
+
5
+ ## React
6
+
7
+ 组件渲染保持纯计算,派生值优先在渲染中计算,不用 effect 同步多个等价状态。effect 用于与外部系统同步并提供清理;依赖完整,避免用关闭 lint 掩盖闭包过期。列表 key 使用稳定业务身份。自定义 hook 封装可复用行为,不成为所有业务逻辑的容器。
8
+
9
+ 保留项目已有请求缓存库,评估缓存失效与请求取消。只有测量或明确引用稳定性需求支持时引入 memo,避免机械包装。SSR 项目区分服务器和客户端边界,不把密钥放入客户端环境变量。
10
+
11
+ ## Vue
12
+
13
+ props 保持单向传递,修改通过事件或明确状态接口。computed 表达派生值,watch 用于外部副作用并管理清理。组合式函数聚合可复用行为,避免隐式全局共享可变状态。使用响应式 API 时注意解构和引用语义,按实际 Vue 版本验证。
14
+
15
+ 跨页面状态使用项目现有 store;局部表单不无条件上移。SSR 场景按请求隔离状态,避免模块级单例泄露不同用户数据。
@@ -0,0 +1,11 @@
1
+ # 状态、请求与交互
2
+
3
+ 区分服务端缓存、URL 状态、表单草稿、组件临时状态和跨页面客户端状态。数据只保留一个权威来源,不把请求缓存再复制到全局 store。筛选和分页需要可分享/刷新时放入 URL,并校验参数。
4
+
5
+ 请求键包含影响结果的筛选、分页和身份范围;账号或租户切换时避免复用旧缓存。竞态采用取消或请求序号防止旧响应覆盖新结果。组件卸载后清理监听、计时器和订阅。
6
+
7
+ 提交期间禁用重复交互有助于体验,但不能代替服务端幂等。乐观更新必须能回滚,并处理多个并发修改的顺序;高风险操作优先等待服务器确认。错误保留用户输入,提供合适的重试入口,重试有副作用的请求要遵循接口协议。
8
+
9
+ 表单区分初始值、草稿和提交 DTO;前端校验用于反馈,服务端仍需校验。清楚呈现字段错误和表单级错误。提供加载、空态、部分失败、离线/超时和无权限状态,是否需要全部实现由任务实际决定。
10
+
11
+ 使用语义化元素、可访问名称和可见焦点;对话框处理焦点进入/退出和键盘关闭,动态错误与加载状态可被辅助技术感知。测试优先模拟真实用户操作,覆盖竞态、重复提交和权限变化,不用组件内部实现快照替代行为验证。
@@ -0,0 +1,11 @@
1
+ # 前端模块与数据边界
2
+
3
+ 按业务功能组织页面、局部组件、请求适配、状态和测试;基础组件库保持无业务依赖。路由页面负责流程组装,业务组件表达业务交互,基础组件表达通用视觉/输入能力。只有确实跨功能复用且语义一致时才提升到 shared。
4
+
5
+ 前端 DTO 与显示模型可分离:日期、金额、枚举显示在适配层转换;未知枚举有安全兜底,不能把未知状态误显示为成功。服务端权限决定可执行操作,前端显隐只是体验控制。
6
+
7
+ 避免组件直接散布 HTTP 地址、身份逻辑和响应解包。统一请求适配需保留取消、状态码、错误详情和追踪标识,不把所有失败压成空数组。
8
+
9
+ 模块对外暴露稳定入口;避免业务 A 引用业务 B 的内部状态。样式、主题和响应式断点沿用项目设计系统,不在多个组件重复定义同一设计值。
10
+
11
+ 新增目录必须有实际职责,不创建占位 service/utils/hooks 文件。重构以用户流程和可验证行为为边界。
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 leiax00
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.