日期：2025-02-09
状态：已确认

第一节：目标与范围​

目标

• 系统侧：在现有芋道后台中增加「技能包」管理能力，运营/管理员可创建、编辑、发布技能包（业务数据落库，供 AI Agent 或其它业务消费）。
• 开发侧：在 Cursor 中提供一个「创建技能包（管理模块）」的 skill，能像 biz-crud-create-page 一样一键生成「技能包」的整条管理链路（表结构 + 字典 + 菜单 + 后端 CRUD + 前端列表/表单/详情），并遵循项目既有规范。

范围

• 技能包在系统内视为一种业务实体：有名称、编码、描述、状态（草稿/已发布等）、版本、所属分类等可配置字段；具体字段在第二节数据模型中确定。
• 管理能力：列表（含筛选）、新增、编辑、删除、发布/下架；详情页可展示包内「技能」列表或配置摘要（首期做简单列表，复杂编排可后期扩展）。
• 生成器 skill：只负责生成「技能包管理」这条 CRUD 链路（含一个技能包表及必要字典/菜单），不生成「包内单个 skill 的 SKILL.md 文件」；若以后需要「从管理页导出为 Cursor skill 目录」，再单独做导出功能。
• 消费方式本期只做数据就绪：表与 API 先有，供前端或内部调用；若已有或计划有 Agent 服务，可直接读同一套 API。

不包含（YAGNI）

• 包内技能的在线编辑器、版本 diff、审批流、多租户隔离（除非现有项目已强依赖租户）。
• 技能包市场、分享、权限到「包内单条技能」的细粒度控制。

成功标准

• 用 skill 生成一遍后，能在后台看到技能包菜单，完成列表/增删改/发布状态切换。
• 生成物符合现有数据库、后端、前端规则（与 lead/source 或 lead/personal 风格一致）。

第二节：数据模型与字典​

主表 ai_skill_package

• 与现有规范一致：主键 id（雪花）、creator/create_time/updater/update_time/deleted、tenant_id（多租户）。
• 业务字段：name（名称）、code（编码，租户内唯一，用于 API/导出）、description（描述，VARCHAR(500) 或 TEXT）、status（状态，见下）、sort（排序，INT 默认 0）、content（TEXT，可选，存包内技能摘要或 JSON，后续可扩展）。
• 索引：uk_ai_skill_package_code_tenant (code, tenant_id, deleted)，idx_ai_skill_package_status (status)，idx_ai_skill_package_sort (sort)。

字典

• skill_package_status：草稿（DRAFT）、已发布（PUBLISHED）、已下架（OFFLINE）。列表筛选、详情、发布/下架操作均用该字典。
• （可选）skill_package_category：如「业务生成」「Agent 技能」等，便于后续分类筛选；若首期不做分类，可不建该字典。

包内技能（首期从简）

• 不单独建「技能项」表，用主表 content 存一段文本或 JSON 即可（例如技能名称列表 + 简要说明），详情页只读展示。若后续需要逐条增删改「包内技能」，再增加 ai_skill_package_item 表与前后端。

菜单与权限

• 一级菜单（示例）：「AI 技能」或放在现有某父级下，path 如 /ai/skill-package。
• 二级：技能包管理，permission 前缀 ai:skill-package:query/create/update/delete，并可加 ai:skill-package:publish 控制发布/下架。

第三节：后端与前端实现要点​

后端

• 模块：放在现有 yudao-module-ai，若当前只有 pom，则在该模块下按规范建包：controller.admin、dal.dataobject.skill、dal.mysql.skill、service.skill、convert.skill、controller.admin.vo.skill（PageReqVO/RespVO/SaveReqVO，按需 SimpleRespVO）。
• 接口约定：Base URL /admin-api/ai/skill-package。提供：分页查询 getPage、详情 get、新增 create、修改 update、删除 delete、发布 publish、下架 offline。权限标识：ai:skill-package:query/create/update/delete，发布/下架可用 ai:skill-package:publish 或复用 update。
• 实现要点：DO 继承 TenantBaseDO，表名 ai_skill_package。发布/下架即把 status 置为 PUBLISHED/OFFLINE 并做幂等与状态校验（如仅草稿可发布、仅已发布可下架）。错误码在 yudao-module-ai 的 ErrorCodeConstants 中新增，Controller 用 @PreAuthorize 与现有风格一致。

前端

• 路由：在 router/routes/modules 下新增 ai.ts（或并入已有 AI 路由），path 如 /ai/skill-package，组件 ai/skill-package/index；列表、新增/编辑、详情对应同一模块下的 index、create、edit、detail。
• 列表页：Page + useVbenVxeGrid，查询项：名称（Input）、编码（Input）、状态（Select，DICT_TYPE.skill_package_status）。表格列：名称、编码、状态（CellDict）、排序、更新时间、操作（编辑/删除/发布/下架，按状态显隐）。API 与后端分页约定一致（pageNo、pageSize、表单条件、排序）。
• 表单（新增/编辑）：名称、编码、描述、排序、状态（草稿时可选）、content（可选，Textarea）。编码新增时必填，编辑时只读或禁用。校验：编码格式、名称非空。
• 详情页：只读展示上述字段；若有 content，以只读区块或简单 JSON/文本展示「包内技能」摘要。
• 发布/下架：列表操作列按钮，调用 publish/offline 接口后刷新列表；可加二次确认（如「确认发布？」）。

与现有风格对齐

• 后端 VO 命名、分页参数、统一返回与 CRM 模块一致；前端 data.ts 中 formSchema/columns、TableAction、权限 ai:skill-package:xxx、i18n key 前缀统一（如 ai.skillPackage.xxx）。组件与数据源遵守 .cursor/skills/biz-crud-create-page/component-data-mapping.md（本业务若无特殊下拉可仅用字典）。

第四节：生成器 Skill 设计​

定位与触发

• 新建项目内 skill：.cursor/skills/create-skill-package-module/，内含 SKILL.md。触发场景：用户说「生成技能包管理模块」「创建技能包管理页」「按 createPage 风格做技能包」等时，Agent 优先使用该 skill。
• 与 biz-crud-create-page 的关系：不替代，复用其规则与参考。本 skill 只针对「技能包」这一固定业务，产出表名、实体名、模块名、菜单/权限前缀、字典类型等均写死在 skill 内，无需用户再走「查询项→表格→功能清单」多步交互；若以后要支持「自定义实体名的技能包」，再考虑引入类似 create-page 的交互。

生成顺序（与 create-page 一致，严禁颠倒）

1. SQL：sql/mysql/ 下新增 ai_skill_package.sql（建表）、ai_skill_package_dict.sql（skill_package_status 等字典，幂等）、ai_skill_package_menu.sql（AI 技能 / 技能包管理菜单及 ai:skill-package:query 等按钮权限，含 role_id=1 的 system_role_menu）。
2. 后端：在 yudao-module-ai 中生成 DO（TenantBaseDO）→ Mapper → Service 接口与 Impl → Controller（/admin-api/ai/skill-package）→ VO（PageReqVO、RespVO、SaveReqVO）；ErrorCodeConstants 中新增错误码；发布/下架在 Service 内做状态流转与校验。
3. 前端：router/routes/modules/ai.ts 中注册列表与 detail/create/edit 路由；views/ai/skill-package/ 下 index.vue、data.ts、create.vue、edit.vue、detail.vue（弹窗 CRUD 则用 modules/form.vue）；api/ai/skill-package/index.ts；i18n 键与菜单名称一致。

Skill 文档必须写清的内容

• 本模块固定参数表：表名 ai_skill_package、模块名 ai、实体名 skillPackage（前端）、权限前缀 ai:skill-package、字典类型 skill_package_status、参考实现路径（可与本设计文档互相引用）。
• 必读规则：.cursor/rules/backend/database.mdc、backend-project-structure.mdc、.cursor/rules/frontend/biz-crud-page-standard.mdc；参考实现指向「技能包」生成后的代码或现有 lead/source 的目录结构说明。
• 生成后校验：要求执行 node .cursor/skills/biz-crud-create-page/scripts/validate-page.mjs ai skill_package --backend（若 validate-page 支持 ai 模块）；或在本 skill 下提供专用 validate-skill-package.mjs，检查 SQL、菜单、路由、views、API、后端 DO/Controller 是否存在且符合约定。

可选

• 本 skill 的 reference.md 中列出「技能包管理」字段与接口清单，便于 Agent 一次生成完整；scripts/ 下仅保留校验脚本，不提供通用代码生成引擎。

第五节：错误处理与验收​

错误处理

• 后端：编码重复返回 400 及明确错误码；发布/下架状态不合法（如对已下架再下架）返回 400 并提示当前状态；删除前可做关联校验（若未来有包内技能表则先判空）。
• 前端：接口失败用项目统一提示；列表加载失败可重试或空状态提示。
• 生成器：校验脚本以非 0 退出并打印缺失项（如「缺少 ai_skill_package_menu.sql」），Agent 按提示补全后重新运行直至通过。

验收标准

• 执行 skill 生成一遍后：执行 SQL、启动后端与前端，能在「AI 技能」下看到「技能包管理」，完成列表筛选、新增、编辑、删除、发布、下架、详情查看；数据落库且状态正确。
• 生成代码通过项目既有 Lint/编译；菜单与权限与设计一致。

总体思路 目标就是两件事： 减少「自动带进来但其实用不到」的上下文 减少「每次对话需要重复扫描的大文件/大结构」 我分三块讲：项目结构级、Cursor 配置级、日常使用习惯级。 一、项目结构 / 忽略规则层面 扩充 .cursorignore，把“永远不需要读”的东西都排掉（你已经忽略了 node_modules 和 backend/target，不错）： 可以考虑再加： 编译产物：frontend/web/dist, frontend/app/android, frontend/app/ios, .log 大型静态资源：**/.png, /.jpg, **/.mp4（如果你几乎不会问这些） 测试快照、coverage：/snapshots/, coverage/ 文档/规范集中到少数文件 把“项目规范、工作流”集中到 CLAUDE.md + 少数 docs/plans/*.md，避免在很多散文件里重复长说明，每次都要被模型扫一遍。 二、Cursor / Claude 配置层面（减少自动上下文） 这些不需要改代码，只是你使用 Cursor 时的习惯： 少用/慎用「自动附加大 Skill」 这次聊天你手动附了 brainstorming，它本身字数不多还好。但类似 superpowers 的大 skill，如果不是每次都需要，可以： 真要用时再贴； 或者把你自己常用的 1–2 个写成更短版 Skill。 控制自动附加的文件数量与大小 在实际使用中： 问问题前，尽量只打开/高亮与你问题最相关的 1–2 个文件； Cursor 会优先把“当前打开文件 + 最近文件”丢给模型，开太多大文件会明显增大 token。 分阶段问问题，而不是一次性贴超长 diff / 多个大文件 比如 App 导航、某一模块的 UI、某个 API 层，尽量拆开问。 对“结构性问题”先问高层（架构、目录），再 drill down 到具体实现。 三、日常使用习惯层面（你和我的交互方式） 这些是你现在就可以改变的操作方式，会立刻省 token： 尽量引用“路径 +行号”而不是整文件粘贴 在 Cursor 里说：

看下 frontend/app/src/navigation/index.tsx 的路由结构 让我自己用只读工具去读，比你复制整个文件到聊天里便宜很多。 大文件只问一个点 不要说“帮我 review 整个线索模块”，而是 先：“帮我理解 ClueOrigin 这块的筛选逻辑” 再：“再看下它和 ClueMain 的关系”，这样每次只需要一小部分上下文。 控制回答详细程度 像你现在这样不要求超长讲解，其实就已经在省 token 了；如果后面你觉得“回答太长”，可以直说： “只给结论和关键代码引用，不要铺垫” 我会按你要求压缩输出。 四、如果你愿意再进阶一点的做法 给 Cursor/Claude 写更短的 RULE / Skill 例如专门为这个项目写一个 RULE.md： 只说明技术栈、目录结构、OpenSpec 工作流的“精简版”； 把长篇解释放在仓库的 docs/，需要时你再手动提示我去看。 把「经常要看的大文档」拆成多个小文件 比如一个 2000 行的 spec，可以拆成按模块的 3–4 个； 这样每次只会读到相关那一份。 简单总结一句 减少 token 的核心就是“缩小自动上下文 + 精准地引用需要看的文件/片段”。 如果你愿意，我可以帮你草拟一版更“节省 token”风格的 .cursorignore 和一个精简版的 RULE 模板，你自己手动去改就行。

Tailscale 是一种基于 WireGuard 协议构建的**零配置虚拟专用网络（VPN）**解决方案，专注于为个人用户和企业提供简单、安全的网络连接。

核心功能​

典型使用场景​

• 远程访问内网服务：从外网安全访问家中的 NAS、Raspberry Pi、服务器等
• 跨地域团队协作：将分布在全球的办公网络和员工设备组成统一网络
• 开发测试环境：快速搭建安全的开发/测试网络，模拟生产环境
• IoT 设备管理：统一管理分散的智能设备，无需公网 IP

技术原理​

1. 基于 WireGuard：使用现代加密协议，性能优于传统 VPN（如 OpenVPN、IPsec）
2. Coordination Server：Tailscale 的控制平面仅负责密钥分发和 NAT 穿透协调
3. DERP Relay：当 P2P 直连失败时，通过中继服务器转发流量（加密）
4. NAT Traversal：自动处理各种 NAT 环境，最大化实现直连

定价模式​

• 个人免费版：最多 20 个设备，基础功能齐全
• 个人 Pro：$4/月，无限设备 + 子网路由
• Team/Business：按用户收费，提供 SSO、审计日志、API 等高级功能

与同类产品对比​

如果你是想搭建一个完全私有的 Tailscale 网络（不依赖 Tailscale 官方服务器），可以了解 Headscale —— 它是 Tailscale 控制服务器的开源实现，支持完全自托管。

Web → App 基于 OpenSpec 的开发流程​

创建日期： 2026-02-04
适用范围： 线索 / 客户等 CRM 业务，从 Web 需求演进到 App 实现

1. 流程总览​

从一个功能/改动诞生，到 App 上线闭环，推荐遵循下面的主流程：

1. 需求进入（通常先在 Web 上提出或实现）
2. 统一业务到主 Spec（openspec/specs/*）
3. 评估是否需要 App 跟进
4. 为 App 创建 / 更新对应的 OpenSpec change（openspec/changes/app-*）
5. 在 change 的 design.md 中完成 App UX 设计（信息架构 + 页面流程 + 布局）
6. 从 design.md 拆分实施任务到 tasks.md
7. 按任务开发、测试 App，并持续回填 Spec / 设计 / 任务
8. 使用 openspec verify 验证，再 archive 完成变更归档

2. 需求进入 → 统一到主 Spec​

目标： 无论 Web 或 App，所有业务规则以 openspec/specs/* 为唯一真源。

• 当有新需求或 Web 行为变更时，先检查：
  • 当前业务是否已经有对应 Spec（例如：lead-pool、personal-leads、customer-conversion 等）。
  • Web 实际行为与 Spec 是否一致。
• 若不一致：
  • 创建一个小的业务同步 change（如 2026-02-xx-sync-lead-spec）。
  • 在该 change 中仅做两件事：
    • 修正/补充主 Spec：更新 openspec/specs/* 中的字段、状态流转、规则说明。
    • 记录原因：在 proposal.md / design.md 中说明“为什么要改 Spec（与历史实现的差异）”。

完成后，Web 与 App 后续均以更新后的主 Spec 为准。

3. 决定是否需要 App 跟进​

在业务 Spec 更新后，进行一次轻量评估：

• 该改动是否影响移动端的核心场景？
  • 例如：线索列表字段调整、转化规则变化、客户关键信息修改等。
• 评估结果：
  • 必须跟进：影响主流程或数据一致性，必须在 App 中同步。
  • 推荐跟进：改善体验，但不是硬性要求，可以合并到后续 App 迭代。
  • 暂不需要：仅 Web 端特有的桌面场景，可暂不做 App 支持。

当结论为“必须/推荐跟进”时，进入下一步，为 App 创建/更新 change。

4. 为 App 创建 / 更新 OpenSpec change​

命名建议：

• openspec/changes/app-<模块>-<目标>，例如：
  • app-lead-mobile-list（线索列表移动端版本）
  • app-customer-conversion-flow（客户转化流程）

proposal.md 建议内容：

• 背景： 关联哪些业务 Spec（链接到 openspec/specs/*）。
• 目标用户： 例如一线销售 / 经理。
• 业务目标： 希望这次在 App 上达成的业务效果（而非技术细节）。
• 范围边界： 这次 App 改动包含/不包含哪些屏幕和操作。

5. 在 design.md 中完成 App UX 设计（先设计再开发）​

design.md 是这条 Web → App 变更在 App 侧的“设计真源”，推荐固定结构如下：

5.1 关联主 Spec 与场景​

• 列出本次改动关联的业务 Spec：
  • 例如：[lead-pool](../../specs/lead-pool/spec.md)、[customer-conversion](../../specs/customer-conversion/spec.md)。
• 用 1–2 句话说明本次在 App 上解决的核心场景：
  • 如：“让销售在移动端快速筛选高意向线索并发起跟进/转化”。

5.2 信息架构（App IA）​

• 列出涉及的 App 屏幕及一句话职责，例如：
  • LeadListScreen：我的线索列表，帮助销售快速找到“现在最值得处理”的线索。
  • LeadDetailScreen：线索详情 + 跟进记录，集中展示决策所需信息。
  • LeadConvertScreen：转化流程，减少误操作，用最少步骤完成转客户。

5.3 用户流程（User Flow）​

• 用步骤方式描述从入口到完成任务的路径，例如：
  • 首页 → 点“线索”入口 → 线索列表 → 筛选 → 详情 → 新增跟进 → 转为客户。
• 对应线索/客户等核心流程可以只写 1–2 条“标准路径”，其余放到 tasks.md 验收里。

5.4 屏幕布局与组件粒度​

• 对关键屏幕（例如线索列表、线索详情）写到组件级：
  • 顶部搜索、快捷筛选 Chips、列表卡片的字段排布、底部主按钮等。
• 对次要屏幕可只写区块级：
  • 顶部标题区、中部表单区、底部操作区。
• 不要求画高保真，只需说明信息密度、主次层级与主要交互。

5.5 状态与反馈​

• 加载中、空数据、错误、权限不足时的表现：
  • 是否有 Skeleton 占位、空态文案、重试按钮等。
• 哪些操作需要 Toast，哪些需要确认弹窗。

5.6 与 Web 的 UX 对齐与差异​

• 明确哪些行为必须与 Web 一致（例如：校验规则、必填字段）。
• 明确为移动端刻意做的差异（例如：字段裁剪、操作合并到底部按钮栏）。

6. 从 design.md 拆分到 tasks.md​

tasks.md 用于驱动实施与测试，建议按以下维度拆分：

1. 屏幕与导航
   • 创建/调整相应的 Screen 与路由。
   • 配置 Tab / Stack 结构与入口位置。
2. 组件与状态
   • 列表卡片、详情块、过滤组件、表单等 UI 任务。
   • 本地 UI 状态（loading/error/selected item 等）。
3. API 与数据流
   • 调用哪些后端接口，如何与 shared API 连接。
   • 使用 Jotai / Zustand 管理哪些业务状态。
4. 验收与测试
   • 从 design.md 的用户流程中抽取手工验收用例。
   • 设计 e2e 场景（登录 → 打开模块 → 执行核心路径）。

开发以 tasks.md 为 TODO 清单执行，过程中有变更应回填：

• 业务规则问题 → 优先修改主 Spec（openspec/specs/*）。
• 只是 UX/实现细节微调 → 更新 design.md / tasks.md。

7. 开发、验证与归档​

7.1 开发与自检​

• 按 tasks.md 完成所有实现任务：
  • 屏幕/组件/导航/状态管理/API 调用。
• 在 App 项目中执行基础自检：
  • npx tsc --noEmit
  • yarn lint
  • 关键路径的手工走查。

7.2 使用 openspec verify​

• 在 verify 阶段对照以下内容逐条检查：
  • proposal.md 中的业务目标是否达成。
  • design.md 中的信息架构、流程、关键 UX 是否已实现。
  • tasks.md 中的实施任务与测试任务是否全部完成。
  • 与主 Spec 的行为是否保持一致，差异是否在设计中有记录。

7.3 archive 归档​

• 验证通过后执行归档，将 change 移入 openspec/changes/archive。
• 归档后的 change 就是这次 Web → App 能力同步的完整“变更记录”，便于后续审计与演进。

8. 推荐落地顺序（线索 / 客户试点）​

1. 选择一条业务（推荐：线索列表 + 线索详情 + 转化）。
2. 校准相关主 Spec（lead-pool、personal-leads、customer-conversion 等）。
3. 新建 openspec/changes/app-<lead-module> change。
4. 按本指南格式完善该 change 的 design.md 与 tasks.md。
5. 驱动一次完整的 App 实施与验收闭环。

完成这条试点后，可以将本文件作为团队在其他模块（待办、机会、Dashboard 等）的共用开发流程规范。

1. 整体架构示意 ┌─────────────────────────────────────────────────────────────────────────────────┐│ 云帆 CRM 技术架构 │├─────────────────────────────────────────────────────────────────────────────────┤│ ││ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ││ │ Web (Vite) │ │ App (RN) │ │ 后端 (SB) │ ││ │ React 19 │ ──ajax─▶│ axios │ ──▶ │ context │ ││ │ Ant Design │ │ Jotai │ │ /api │ ││ └─────────────┘ └─────────────┘ └──────┬──────┘ ││ │ │ │ ││ │ baseUrl: /api │ │ ││ └────────────────────────┴────────────────────────┘ ││ │ ││ ┌─────────────┼─────────────┐ ││ ▼ ▼ ▼ ││ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ││ │ MySQL │ │ Redis │ │ RabbitMQ │ │ 存储/CDN │ ││ │ 8.0 │ │ 7 │ │ (可选?) │ │ 本地/OSS │ ││ └──────────┘ └──────────┘ └──────────┘ └──────────┘ ││ │└─────────────────────────────────────────────────────────────────────────────────┘
2. 后端架构（Java + Spring Boot） 2.1 分层与职责 层 位置 职责 Controller controller/ REST 接口，参数校验，调用 Service Service service/ + impl/ 业务逻辑，事务边界 Mapper mapper/ MyBatis-Plus，单表/批量 Entity entity/ 表映射；DTO 在 dto/、common/ 下 Common common/ 缓存、安全、审计、消息、通知、存储、调度等 统一响应：Result（code / message / data / timestamp）。全局异常：GlobalExceptionHandler。 2.2 已做得不错的地方 分层清晰：Controller → Service → Mapper，DTO 与 Entity 分离。 统一出口：Result、全局异常、Knife4j 文档。 基础设施：Redis 缓存（枚举/国家/配置）、Druid 连接池与监控、MyBatis-Plus 分页与逻辑删除。 扩展模块：审计、GDPR、数据隔离（按国家）、消息（RabbitMQ）、通知（邮件/企微）、定时任务、存储抽象（本地/OSS）。 部署：docker-compose 含 MySQL、Redis、应用，环境变量清晰。 2.3 可优化点（架构层面） 点 现状 建议 API 版本与路径 大部分接口无版本（如 /api/lead-pool），仅 AiCrawlerSourceController 用 /api/v1/ai-crawler-sources 统一约定：要么全加 /api/v1/ 前缀，要么全不加，并文档化，便于以后做 v2 不破坏现有前端。 安全 SecurityConfig 当前 anyRequest().permitAll()，仅靠请求头 auth-token 若已上生产，建议在 Security 里显式配置需认证的路径、放行文档/健康检查等，避免“默认全放行”的误用。 RabbitMQ 与部署 代码里有 RabbitMQ 配置与消费者，但 docker-compose 未包含 RabbitMQ 要么在 docker-compose 中增加 RabbitMQ 服务，要么用 @ConditionalOnProperty 等让消息模块在未配置时不可用，避免本地/测试环境因连不上 MQ 启动失败。 MyBatis 二级缓存 application.yml 里 cache-enabled: false 保持关闭是稳妥的；若以后要开，需考虑多实例与 Redis 等集中缓存，避免本地缓存不一致。
3. 前端 Web 架构（React + Vite） 3.1 结构 入口：AppRouter 用 ~pages-config 生成路由，根级 Suspense + useRoutes。 请求：统一 axios 实例，baseUrl /api，请求头带 auth-token，拦截器处理 loading/成功/错误/取消。 页面：pages/ 下按业务分目录（lead-pool、personal-leads、todos、users 等），列表页多为「Form 筛 + Table 分页」。 配置：config-hoc（权限、标题、抽屉、弹窗）、menus、多环境 config。 3.2 可优化点 点 说明 路由懒加载 需确认 @ts-max/vite-plugin-pages-config 生成的路由是否按页面 React.lazy；若否，首屏会包含所有页面 chunk，可考虑按路由懒加载以减小首包。 请求缓存 未使用 React Query/SWR 等，重复进入同一列表会重复请求；可对只读列表/详情做短时缓存或 stale-while-revalidate，减轻后端压力、提升体验。 类型与接口 列表/详情类型多在各自 pages/xxx/types.ts；若后端有 OpenAPI/Knife4j 生成类型，可考虑统一生成前端类型，减少手写不一致。
4. App 架构（React Native） 4.1 结构 API：api/ 下按领域拆模块（todo、customer、clue、brand 等），client 统一请求。 状态：Jotai + Zustand，MMKV 持久化。 列表：FlashList；图片：fast-image。 导航：React Navigation v7 静态导航；大量 screens/ 与业务组件。 4.2 可优化点 点 说明 与后端对齐 App 的 api 模块（如 approval、contract、invoice）若与当前后端 controller 不完全对应，需确认是历史模块、多后端，还是待收敛；对齐后可减少重复与歧义。 共享类型 若 Web 与 App 共用同一套后端 API，可考虑把通用类型/接口定义放到 monorepo 公共包或从 OpenAPI 生成双端类型，避免两套定义漂移。
5. 跨端与一致性 维度 现状 可优化 认证 Web：auth-token 头；App：需看 authService 是否同一套 统一 token 存储、刷新、过期处理与错误码，便于双端体验一致。 API 契约 后端 Knife4j/OpenAPI，前端手写类型 用 OpenAPI 生成 TS 类型或 SDK，减少手写、保证与文档一致。 错误与多语言 后端统一异常、前端拦截器处理；i18n 各端自有 错误码与 key 统一约定，便于前端做统一错误文案与多语言映射。

整体设计思路很成熟：先设计后开发、TDD、AI 辅助、分层架构清晰、技术栈选型合理，尤其是前后端均有明确的目录与职责划分，工程化意识强。以下是我认为可以进一步增强的点（按优先级排序）：

1. 设计与需求阶段（最关键） 问题：目前流程偏“文档驱动”，但缺少“可验证”的设计输出。 建议改进：

需求文档增加可执行验收标准（类似 BDD 的 Given/When/Then） 接口设计先行：OpenAPI/Swagger 规范文件先落地，再联动前后端生成骨架（提升一致性） UI 设计到组件库：明确把 Figma/Google Stitch 的组件映射到 src/components/ui，形成“设计-代码”映射表 2) 测试策略（覆盖层面可以更系统化） 问题：测试说明较全，但缺少“测试金字塔”与覆盖标准 建议改进：

明确测试层级覆盖率要求（Unit 70%+ / Integration 30%+ / E2E 关键路径） 前端补充：组件快照测试 + 交互测试标准 后端补充：数据库迁移 + Repository 层集成测试 加入测试基线指标（如每个模块至少 X 条关键用例） 3) API 与契约治理（前后端协作效率核心） 建议改进：

引入 API Contract：例如 OpenAPI + 自动生成 TypeScript Client 确保 Response/Error Schema 统一，减少“前端猜字段” 约定分页、筛选、排序的统一格式（目前未明确） 4) 技术栈维持与演进策略 建议改进：

明确 依赖升级策略（如每季度升级 Node/React Native / Spring Boot） 关键基础库（如状态管理、UI组件、网络层）要明确“替换成本与治理原则” 5) AI 辅助流程可量化 建议改进：

增加 AI 产出校验指标（例如：自动生成代码必须通过 lint/test、覆盖率达标） 建议引入 Prompt 模版规范（特别是针对生成测试/接口/组件） 6) 数据与缓存策略 建议补充：

前端：离线策略、缓存过期、断网行为未描述 后端：Redis 缓存失效策略、热点数据处理方式 我对整体评分（主观） 架构合理性：9/10 工程可执行性：8/10 协作效率与质量保障：7.5/10（改进空间主要在契约、测试、AI流程量化） 如果你愿意，我可以帮你进一步完善以下内容之一：

输出一份完整的“前后端接口契约模板” 输出可直接使用的“测试策略与覆盖率指标” 整理成可执行的“AI辅助开发流程规范”文档 想先从哪一部分强化？

✅ 前后端接口契约模板（OpenAPI 3.1） 目标：统一字段、响应结构、分页规则、错误码与安全策略 适配你当前后端 Spring Boot + 前端 TS 项目

一、契约约定（必须遵守）

1. URL 规范 基础路径：/api 资源名使用复数名词：/users、/orders 查询条件用 query string：/users?status=active
2. 时间格式 全部使用 ISO 8601：2026-01-21T12:30:45+08:00
3. 统一响应结构

{
  "code": 0,
  "message": "success",
  "data": { },
  "traceId": "8f9a..."
}

4. 分页标准 参数：page（默认 1），pageSize（默认 20） 返回：

{
  "list": [],
  "page": 1,
  "pageSize": 20,
  "total": 128
}

5. 错误返回 所有错误走统一结构 HTTP 状态码区分错误类型（401/403/404/422/500） 二、OpenAPI 3.1 模板（可直接使用）

openapi: 3.1.0
info:
  title: AiDrive API Contract
  version: 1.0.0
  description: |
    前后端统一接口契约。所有接口返回统一结构。
servers:
  - url: /api
tags:
  - name: Auth
  - name: User
 
security:
  - bearerAuth: []
 
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
 
  parameters:
    Page:
      name: page
      in: query
      schema: { type: integer, minimum: 1, default: 1 }
    PageSize:
      name: pageSize
      in: query
      schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
    Sort:
      name: sort
      in: query
      description: "如: createdAt desc"
      schema: { type: string }
 
  schemas:
    ApiResponse:
      type: object
      required: [code, message, data, traceId]
      properties:
        code: { type: integer, description: "0=成功，非0=失败" }
        message: { type: string }
        data: {}
        traceId: { type: string }
 
    ErrorResponse:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            data:
              type: object
              properties:
                fieldErrors:
                  type: array
                  items:
                    type: object
                    properties:
                      field: { type: string }
                      message: { type: string }
 
    PageResult:
      type: object
      required: [list, page, pageSize, total]
      properties:
        list:
          type: array
          items: {}
        page: { type: integer }
        pageSize: { type: integer }
        total: { type: integer }
 
    User:
      type: object
      required: [id, username, name, role, createdAt]
      properties:
        id: { type: integer }
        username: { type: string }
        name: { type: string }
        role: { type: string, example: "ADMIN" }
        status: { type: string, example: "ACTIVE" }
        createdAt: { type: string, format: date-time }
 
    LoginRequest:
      type: object
      required: [username, password]
      properties:
        username: { type: string }
        password: { type: string }
 
    LoginResponse:
      type: object
      required: [token, expiresIn]
      properties:
        token: { type: string }
        expiresIn: { type: integer, description: "秒" }
 
    CreateUserRequest:
      type: object
      required: [username, name, role]
      properties:
        username: { type: string }
        name: { type: string }
        role: { type: string }
 
  responses:
    Unauthorized:
      description: 未登录/Token失效
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ErrorResponse' }
    Forbidden:
      description: 无权限
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ErrorResponse' }
    NotFound:
      description: 资源不存在
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ErrorResponse' }
    ValidationError:
      description: 参数校验失败
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ErrorResponse' }
 
paths:
  /auth/login:
    post:
      tags: [Auth]
      summary: 用户登录
      security: []  # 登录接口不需要JWT
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/LoginRequest' }
      responses:
        '200':
          description: 登录成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data: { $ref: '#/components/schemas/LoginResponse' }
        '422': { $ref: '#/components/responses/ValidationError' }
 
  /users:
    get:
      tags: [User]
      summary: 用户分页列表
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/Sort'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        allOf:
                          - $ref: '#/components/schemas/PageResult'
                          - type: object
                            properties:
                              list:
                                type: array
                                items: { $ref: '#/components/schemas/User' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
    post:
      tags: [User]
      summary: 创建用户
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CreateUserRequest' }
      responses:
        '200':
          description: 创建成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data: { $ref: '#/components/schemas/User' }
        '422': { $ref: '#/components/responses/ValidationError' }
 
  /users/{id}:
    get:
      tags: [User]
      summary: 用户详情
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data: { $ref: '#/components/schemas/User' }
        '404': { $ref: '#/components/responses/NotFound' }

三、可选增强（建议补充） ✅ 错误码枚举表（与后端 ResultCode 对齐） ✅ 字段级校验规范（长度、格式、枚举） ✅ OpenAPI 自动生成 TS Client 推荐：openapi-generator-cli 或 openapi-typescript 如果你希望，我可以下一步帮你输出：

✅ “错误码规范与字段校验规范模板” ✅ “与 TypeScript Client 自动生成对接方案” ✅ “你现有后端 ResultCode 对应到 OpenAPI 的映射”

你要继续完善哪一块？

微信公众号​

一、什么是可执行验收标准？​

可执行验收标准是将需求转化为可测试、可自动化的具体规格。它使用特定格式（通常是Given-When-Then）来描述功能的行为，可以直接转换为自动化测试用例。

二、可执行验收标准的好处​

1. 明确性：消除需求歧义
2. 可测试性：直接转换为测试用例
3. 自动化：支持BDD（行为驱动开发）
4. 一致性：开发、测试、产品理解一致
5. 可追踪：需求与测试直接对应

三、常用格式​

1. Gherkin语言（Given-When-Then）​

最常用的格式，被Cucumber、SpecFlow等工具支持。

Feature: 用户登录功能
  作为一个已注册用户
  我想要登录系统
  以便访问我的个人资料
  
  Scenario: 使用正确的用户名和密码登录
    Given 用户已注册且账户有效
    When 在登录页面输入正确的用户名"admin"和密码"123456"
    And 点击登录按钮
    Then 应该跳转到用户主页
    And 页面应显示欢迎信息"欢迎回来，admin"
    
  Scenario: 使用错误的密码登录
    Given 用户已注册
    When 在登录页面输入用户名"admin"和错误密码"wrong"
    And 点击登录按钮
    Then 页面应显示错误消息"密码错误"
    And 用户应该保持在登录页面

2. 表格格式​

适合参数化场景和数据驱动测试。

Scenario Outline: 用户登录验证
  Given 用户"<username>"已注册
  When 输入用户名"<username>"和密码"<password>"
  And 点击登录按钮
  Then 登录结果应为"<result>"
  
  Examples:
    | username | password | result     |
    | admin    | 123456   | 成功       |
    | admin    | wrong    | 密码错误   |
    | unknown  | 123456   | 用户不存在 |
    |          | 123456   | 用户名为空 |

四、在需求文档中的具体实现​

示例需求文档结构​

# 需求文档：用户管理系统

## 1. 概述
- 目标：实现用户注册、登录、资料管理功能
- 范围：Web端用户管理模块
- 优先级：P0
- 预估工时：5人日

## 2. 功能需求

### 2.1 用户登录功能
**需求描述**：已注册用户可以通过用户名和密码登录系统

**验收标准**：

| ID | 描述 | 优先级 | 状态 |
|----|------|--------|------|
| UC-001 | 用户使用正确的用户名和密码登录 | P0 | 待办 |
| UC-002 | 用户使用错误的密码登录 | P0 | 待办 |
| UC-003 | 用户使用不存在的用户名登录 | P1 | 待办 |

**可执行验收标准**：

#### UC-001: 成功登录
```gherkin
Feature: 用户登录
  Scenario: 使用正确的用户名和密码登录
    Given 用户"testuser"已注册且账户状态为"active"
    And 用户在登录页面
    When 输入用户名"testuser"
    And 输入密码"Test@123"
    And 点击"登录"按钮
    Then 应该跳转到首页"/dashboard"
    And 页面应显示欢迎消息"欢迎回来，testuser"
    And 导航栏应显示"注销"按钮
    And 应该记录登录日志
    And Cookie中应设置有效的sessionId

UC-002: 密码错误​

Feature: 用户登录
  Scenario: 使用错误的密码登录
    Given 用户"testuser"已注册
    And 用户在登录页面
    When 输入用户名"testuser"
    And 输入密码"WrongPassword123"
    And 点击"登录"按钮
    Then 页面应显示错误提示"用户名或密码错误"
    And 输入框应清空密码字段
    And 登录按钮应重新可用
    And URL应保持不变
    And 不应创建会话

2.2 用户注册功能​

可执行验收标准：

Feature: 用户注册
  Scenario Outline: 新用户注册验证
    Given 用户访问注册页面
    When 填写注册信息：
      | 字段       | 值           |
      | 用户名     | <username>   |
      | 邮箱       | <email>      |
      | 密码       | <password>   |
      | 确认密码   | <confirm>    |
    And 点击"注册"按钮
    Then 应该<result>
    
    Examples: 有效注册
      | username | email              | password  | confirm   | result                          |
      | alice    | alice@test.com     | Pass123!  | Pass123!  | 显示成功消息并跳转到登录页面    |
      
    Examples: 无效注册
      | username | email           | password  | confirm   | result                          |
      | ab       | alice@test.com  | Pass123!  | Pass123!  | 提示"用户名长度至少3个字符"     |
      | alice    | invalid-email   | Pass123!  | Pass123!  | 提示"邮箱格式不正确"           |
      | alice    | alice@test.com  | 123456    | 123456    | 提示"密码必须包含字母和特殊字符"|
      | alice    | alice@test.com  | Pass123!  | Different | 提示"两次输入的密码不一致"     |

五、最佳实践​

1. 编写原则​

# ✅ DO - 好的做法
Scenario: 用户成功下单
  Given 用户已登录
  And 购物车中有商品"iPhone 15"
  When 用户点击"立即购买"
  And 选择"微信支付"
  And 点击"确认支付"
  Then 应跳转到订单详情页面
  And 订单状态应为"已支付"
  And 应发送订单确认邮件
  And 应扣减商品库存

# ❌ DON'T - 避免的做法
Scenario: 用户买东西
  Given 有东西
  When 弄一下
  Then 搞定了

2. 原子性原则​

每个场景应该只测试一个具体功能点。

# ❌ 不好 - 包含多个不相关的验证
Scenario: 综合验证
  Given 用户登录
  When 修改个人资料
  And 下订单
  Then 资料应该更新
  And 订单应该创建
  
# ✅ 好 - 单一职责
Scenario: 修改个人资料
  Given 用户已登录
  When 修改邮箱为"new@email.com"
  And 点击保存
  Then 应显示"保存成功"
  And 用户邮箱应更新为"new@email.com"

3. 使用背景（Background）​

避免重复的Given步骤。

Feature: 购物车管理
  
  Background: 用户已登录且有商品
    Given 用户"testuser"已登录
    And 商品"iPhone 15"存在
    And 商品"MacBook Pro"存在
    
  Scenario: 添加商品到购物车
    When 用户将商品"iPhone 15"添加到购物车
    Then 购物车中应有1件"iPhone 15"
    
  Scenario: 从购物车移除商品
    Given 购物车中有商品"iPhone 15"
    When 用户从购物车移除"iPhone 15"
    Then 购物车应为空

六、完整示例模板​

# 需求文档模板

## 1. 功能名称
[功能简要描述]

### 1.1 用户故事
**作为** [角色]
**我想要** [功能]
**以便** [价值/目标]

### 1.2 功能描述
[详细描述功能]

### 1.3 验收标准
| ID | 描述 | 优先级 | 状态 | 测试负责人 |
|----|------|--------|------|------------|
| AC-001 | [标准1] | P0 | 待办 | [姓名] |
| AC-002 | [标准2] | P1 | 待办 | [姓名] |

### 1.4 可执行验收标准
```gherkin
Feature: [功能名称]
  [可选的背景描述]
  
  @smoke @P0
  Scenario: [场景1描述]
    Given [前置条件]
    When [操作步骤]
    Then [预期结果]
    
  @regression @P1  
  Scenario: [场景2描述]
    Given [前置条件]
    When [操作步骤]
    Then [预期结果]
    
  Scenario Outline: [参数化场景]
    Given [前置条件]
    When [操作步骤]
    Then [预期结果]
    
    Examples:
      | 参数1 | 参数2 | 预期结果 |
      | val1 | val2 | result1 |
      | val3 | val4 | result2 |

1.5 技术约束​

• [约束1]
• [约束2]

1.6 非功能需求​

## 七、在开发流程中的使用

### 1. 需求评审阶段
```yaml
步骤：
  1. 产品经理编写验收标准草稿
  2. 开发、测试、产品一起评审
  3. 修正不清晰或不可测试的标准
  4. 确定验收条件的优先级
  
产出物：
  - 评审通过的验收标准
  - 明确的需求优先级

2. 开发实现阶段​

步骤：
  1. 开发根据验收标准实现功能
  2. 测试根据验收标准编写自动化测试
  3. 运行自动化测试验证实现
  
产出物：
  - 实现的功能代码
  - 自动化测试脚本
  - 测试执行报告

3. 验收测试阶段​

步骤：
  1. 执行自动化验收测试
  2. 手动验收（如有需要）
  3. 确认所有验收标准已满足
  4. 产品经理签字确认
  
产出物：
  - 验收测试报告
  - 验收确认单

八、工具支持​

1. 文档工具​

• Confluence + Xray：需求与测试管理
• JIRA + Zephyr：需求跟踪与测试管理
• Azure DevOps：完整的DevOps工具链

2. BDD工具​

• Cucumber：Java/Ruby/JavaScript
• SpecFlow：.NET平台
• Behat：PHP平台
• Behave：Python平台

3. 自动化测试框架​

// Cucumber + Selenium 示例
const { Given, When, Then } = require('@cucumber/cucumber');
const { By, until } = require('selenium-webdriver');

Given('用户已登录', async function() {
  await this.driver.get('http://localhost:3000/login');
  await this.driver.findElement(By.id('username')).sendKeys('testuser');
  await this.driver.findElement(By.id('password')).sendKeys('password');
  await this.driver.findElement(By.id('login-btn')).click();
});

When('用户搜索{string}', async function(keyword) {
  await this.driver.findElement(By.id('search')).sendKeys(keyword);
  await this.driver.findElement(By.id('search-btn')).click();
});

九、指标和度量​

1. 覆盖率指标​

需求覆盖率: 95%  # (有验收标准的需求数 / 总需求数) * 100%
测试通过率: 98%  # (通过的验收测试数 / 总验收测试数) * 100%
自动化率: 85%    # (可自动化验收标准数 / 总验收标准数) * 100%

2. 质量门禁​

验收标准:
  - 所有P0级验收标准必须100%通过
  - 整体验收标准通过率不低于95%
  - 关键业务场景必须包含自动化测试
  
文档质量:
  - 每个需求必须包含可执行验收标准
  - 验收标准必须经过三方评审
  - 验收标准必须清晰、可测试

十、常见错误和避免方法​

1. 避免实现细节​

# ❌ 不好 - 包含实现细节
When 点击class为"btn-primary"的按钮
Then 应该设置localStorage中的token

# ✅ 好 - 关注业务行为
When 点击登录按钮
Then 用户应该成功登录

2. 避免重复步骤​

# ❌ 不好 - 重复步骤
Scenario: 测试A
  Given 打开浏览器
  And 访问登录页面
  # ... 其他步骤
  
Scenario: 测试B  
  Given 打开浏览器
  And 访问登录页面
  # ... 其他步骤

# ✅ 好 - 使用Background
Background:
  Given 打开浏览器
  And 访问登录页面
  
Scenario: 测试A
  # ... 测试步骤
  
Scenario: 测试B
  # ... 测试步骤

3. 保持独立性​

# ❌ 不好 - 场景间有依赖
Scenario: 创建订单
  Given 用户登录
  When 创建订单
  Then 订单创建成功
  
Scenario: 查看订单
  # 依赖于上一个场景创建的订单
  When 查看订单列表
  Then 应该看到订单

# ✅ 好 - 每个场景自包含
Scenario: 查看订单
  Given 用户已登录
  And 系统中存在用户"testuser"的订单
  When 用户查看订单列表
  Then 应该看到订单

总结​

在需求文档中增加可执行验收标准的价值：

1. 对齐期望：确保所有干系人对需求理解相同
2. 自动化基础：直接转换为自动化测试
3. 文档即测试：需求文档本身就可以执行
4. 持续反馈：在开发过程中持续验证
5. 质量保证：明确的验收条件确保交付质量

通过实施可执行验收标准，团队可以显著提高需求质量、减少返工、加快交付速度，并建立持续质量保证的机制。

微信公众号​

Claude Code 的 permission-mode 参数提供了不同级别的权限控制模式，每种模式适用于不同的开发场景和安全需求。以下是各模式的详细适用场景、注意事项及对比分析。

一、permission-mode 各模式详解​

1. plan 模式（默认推荐）​

核心机制：Claude 会展示所有操作计划（如文件修改、命令执行），但不会自动执行，需要用户手动确认每个操作。

适用场景：

• 初次使用或不确定场景：当对 Claude 的代码修改能力存疑时，先查看计划再决定
• 关键代码修改：涉及核心业务逻辑、数据库操作、生产环境配置等敏感修改
• 团队协作环境：确保所有修改都经过人工审核，避免误操作影响他人
• 学习/教学场景：让学生理解 AI 的修改意图和逻辑

注意事项：

• 需要频繁手动确认，可能影响开发流畅度
• 对于大量重复性操作（如批量重命名、格式化）效率较低
• 建议配合快捷键（如 Cmd+Enter 快速确认）提升效率

典型使用命令：

claude --permission-mode plan
# 或启动后使用：/permission-mode plan

2. acceptEdits 模式​

核心机制：自动接受文件编辑操作（如代码修改、文件创建），但其他操作（如执行命令、网络请求）仍需确认。

适用场景：

• 日常开发工作流：代码重构、bug 修复、功能开发等常规编码任务
• 信任 Claude 的代码修改能力：经过验证确认 Claude 的修改质量可靠
• 快速迭代场景：需要频繁修改代码但不想频繁确认
• 个人项目开发：风险可控的环境下提升效率

注意事项：

• 必须确保有版本控制（Git），以便回滚错误修改
• 建议先在小范围测试，确认修改逻辑正确后再推广使用
• 对于关键文件（如配置文件、数据库迁移脚本）仍建议手动确认
• 可能意外覆盖未保存的手工修改

典型使用命令：

claude --permission-mode acceptEdits

3. acceptAll 模式​

核心机制：自动接受所有操作，包括文件编辑、命令执行、网络请求等。

适用场景：

• 高度信任环境：如沙盒环境、测试环境、个人开发机
• 自动化脚本场景：与 CI/CD 集成，自动执行代码优化任务
• 批量处理任务：需要执行大量命令或操作时
• 演示/原型开发：快速验证想法，不关心具体执行细节

注意事项：

• 风险极高：可能执行危险命令（如 rm -rf）、意外修改系统文件
• 强烈不推荐在生产环境或重要项目中使用
• 必须配合严格的权限配置（permissions.allow 白名单）
• 建议仅在容器化环境或虚拟机中使用

典型使用命令：

claude --permission-mode acceptAll

4. ask 模式（传统模式）​

核心机制：对每个操作都弹出确认对话框，无论类型。

适用场景：

• 最高安全级别需求：金融系统、医疗系统等对安全性要求极高的场景
• 审计合规要求：需要记录所有操作的场景
• 完全不信任环境：使用第三方 AI 工具或不确定来源的代码

注意事项：

• 开发体验最差：频繁中断，严重影响效率
• 仅适用于极端安全场景
• 实际使用中很少采用，通常用 plan 模式替代

典型使用命令：

claude --permission-mode ask

二、各模式对比总结​

三、实际使用建议​

1. 渐进式采用策略​

• 新手阶段：使用 plan 模式，熟悉 Claude 的操作模式
• 日常开发：切换到 acceptEdits 模式，配合 Git 版本控制
• 特定任务：临时切换到 acceptAll 处理批量任务，完成后立即切换回安全模式

2. 安全配置组合​

无论使用哪种模式，都应配置 permissions.allow 白名单：

{
  "permissions": {
    "allow": [
      "Edit(src/**/*.js)",  // 限制文件操作范围
      "Bash(git status)",   // 只允许特定命令
      "Bash(npm run build)"
    ],
    "deny": [
      "Bash(rm -rf *)",     // 明确禁止危险操作
      "Edit(secrets/**/*)"
    ]
  }
}

关键原则：权限模式控制"是否自动执行"，权限配置控制"能执行什么"。两者结合才能实现真正的安全控制。

3. 环境隔离策略​

• 个人开发机：可使用 acceptEdits 模式
• 生产环境/团队项目：建议使用 plan 模式或严格的白名单
• CI/CD 流水线：使用 acceptAll 但限制在容器内执行，并配置最小权限

4. 常见陷阱与规避​

• 陷阱1：在 acceptEdits 模式下误修改配置文件 → 解决方案：将配置文件加入 deny 列表
• 陷阱2：acceptAll 模式下执行了危险命令 → 解决方案：使用容器隔离，或配置严格的 allow 列表
• 陷阱3：忘记切换回安全模式 → 解决方案：在 .claude/settings.json 中设置默认模式为 plan

5. 模式切换技巧​

• 命令行启动时指定：claude --permission-mode acceptEdits
• 会话中动态切换：输入 /permission-mode plan 即可切换
• 查看当前模式：输入 /permission-mode 查看状态

四、场景化使用示例​

场景1：日常功能开发​

# 启动时使用 acceptEdits 模式，提升效率
claude --permission-mode acceptEdits

# 配合权限配置，限制操作范围
# 在 .claude/settings.json 中配置：
{
  "permissions": {
    "allow": [
      "Edit(src/**/*.ts)",
      "Edit(src/**/*.vue)",
      "Bash(git add *)",
      "Bash(npm run dev)"
    ]
  }
}

场景2：代码审查/学习​

# 使用 plan 模式，查看所有修改建议
claude --permission-mode plan

# 对每个修改建议进行人工确认
# 适合代码重构、性能优化等需要谨慎处理的场景

场景3：自动化脚本​

# 在 CI/CD 流水线中使用 acceptAll 模式
# 但必须配合容器隔离和严格权限
docker run --rm -v $(pwd):/app claude-code \
  --permission-mode acceptAll \
  --allowedTools "Edit,Bash(npm run build)"

五、总结建议​

1. 默认使用 plan 模式：安全第一，适合大多数场景
2. 个人项目可尝试 acceptEdits：配合 Git 版本控制，效率提升明显
3. 绝对避免在生产环境使用 acceptAll：除非有完善的隔离和审计机制
4. 权限配置是核心：无论使用哪种模式，都必须配置 permissions.allow 白名单
5. 根据场景灵活切换：不同任务使用不同模式，不要一成不变

记住：权限模式只是控制"是否自动执行"，真正的安全防线在于权限配置的白名单机制。建议从 plan 模式开始，逐步建立对 Claude 的信任，再根据实际需求调整模式。

微信公众号​

Claude Code 本身不直接生成 Stitch 的设计内容（如设计稿、原型图等视觉素材），但可以通过工作流整合，利用 Stitch 生成设计原型后，再用 Claude Code 将其转换为代码实现。以下是完整的操作流程和替代方案：

一、核心工作流：Stitch + Claude Code 协作模式​

标准流程（推荐）​

第1步：用 Stitch 生成设计原型

• 访问 https://stitch.withgoogle.com/（需科学上网）
• 通过自然语言描述或上传参考图，让 Stitch 生成交互式原型
• 导出设计素材：HTML 预览、截图、设计规范文档

第2步：将 Stitch 输出喂给 Claude Code

• 方式1：直接复制 HTML 代码 → 粘贴到 Claude Code 对话中，要求优化或转换为框架代码
• 方式2：使用截图 + 设计规范 → 上传截图，同时提供 Stitch 生成的颜色、字体等设计 token
• 方式3：通过 MCP 集成（需配置）→ 设置 Stitch MCP 服务器，让 Claude Code 直接读取设计数据

第3步：Claude Code 生成生产代码

• 基于 Stitch 的设计输入，让 Claude Code 生成 React/Vue/Next.js 等框架代码
• 提示词示例：

  请基于这个 Stitch 生成的设计原型（见截图/HTML），将其转换为一个完整的 Next.js 页面组件。保持原设计风格，使用 Tailwind CSS 实现响应式布局。
  

关键提示技巧​

1. 提供完整上下文：不要只给截图，同时提供：

   • 颜色色号（如 #FFD500）
   • 字体系统（字体族、大小、字重）
   • 间距尺度（如 Tailwind 的 p-4、m-6）
   • 组件样式细节（圆角、阴影、边框）

2. 迭代优化：首版代码通常不完美，通过精准反馈持续优化：

   按钮的悬停效果需要更明显，请将背景色从 #f0f0f0 改为 #e0e0e0，并添加 1px 边框
   

3. 生成风格指南：让 Claude Code 基于 Stitch 设计输出一份 STYLE_GUIDE.md，作为后续开发的标准参考

二、替代方案（无需 Stitch）​

如果无法访问 Stitch 或想简化流程，Claude Code 也支持直接生成设计内容，但效果和 Stitch 不同：

方案1：纯文本描述生成 UI​

• 优势：无需外部工具，完全在 Claude Code 内完成
• 劣势：视觉质量依赖提示词精度，容易有"AI味"
• 提示词示例：

  请设计一个现代简约风格的登录页面，包含：
  - 左侧品牌 logo 和 slogan
  - 右侧表单（邮箱、密码、记住我、登录按钮）
  - 使用柔和的蓝色系配色
  - 响应式布局，在移动端堆叠排列
  输出完整的 HTML + CSS 代码
  

方案2：图片分析 + 代码生成​

• 上传参考图（如 Dribbble 设计稿、网站截图）
• 让 Claude Code 分析并复刻设计
• 注意：此方法对复杂布局识别有限，需多次迭代

方案3：使用 Figma MCP 集成​

• 配置 Figma MCP 服务器（需 Figma Dev Mode）
• Claude Code 可直接读取 Figma 设计文件
• 生成代码的还原度更高，但配置较复杂

三、常见问题与解决方案​

四、总结：选择建议​

• 如果需要高质量设计原型 → 优先用 Stitch 生成，再交给 Claude Code 转代码
• 如果追求快速原型 → 直接用 Claude Code 描述生成（质量要求不高时）
• 如果已有 Figma 设计稿 → 配置 Figma MCP，跳过 Stitch 环节
• 如果无法访问 Stitch → 用方案1/2，或寻找其他设计工具（如 V0.dev、Bolt）

重要提醒：无论哪种方式，Claude Code 生成的代码都需要人工审查和优化，特别是交互逻辑、性能优化、代码结构等方面。AI工具是辅助，不是完全替代。

补充说明：如果您的"stitch设计内容"指的是其他含义（如刺绣图案、数据缝合等），请补充说明具体需求，我会重新为您解答。

微信公众号​

在AI编程时代，人的角色定位正在经历从 "执行者"到"架构师" 的根本性转变。这不仅是技能的重塑，更是价值重心的迁移：

核心价值层：不可替代的人类特质​

1. 意图翻译官 将模糊的业务需求、人性洞察转化为精确的技术目标。AI擅长"怎么做"，但"为什么做"和"做什么"仍是人类主战场——理解CEO深夜邮件里的焦虑、感知用户没说出口的痛点、权衡商业伦理与增长。

2. 系统架构师 AI能生成代码片段，但难以处理跨系统的复杂权衡：在性能、成本、可维护性、扩展性之间的多维博弈。这需要对业务生命周期、技术债的复利效应、组织能力的深层理解。

3. 异常处理者 当系统出现AI训练数据之外的边缘案例、伦理困境或黑天鹅事件时，人类提供最后的判断锚点。AI处理"大概率"，人类守住院线——特别是涉及生命安全、社会公平的决策。

4. 创造力催化剂 用AI作为认知外骨骼，而非替代品。人类提出"如果让用户像玩游戏一样完成报税"的突破性假设，AI负责实现细节。真正的创新发生在人机对话的张力中。

能力迁移：从编码到编辑​

• 代码审查 → 意图审查：不只是检查漏洞，更要问"这段AI生成的代码是否真正解决了问题本质"
• 写函数 → 编故事：用叙事能力定义产品愿景，让AI在故事框架下生成技术细节
• 调试代码 → 调试假设：当AI输出不如预期时，反思的是商业假设而非语法错误

警惕两个陷阱​

⚠️ 过度依赖陷阱：把AI当神谕，丧失批判性思维
⚠️ 技能空心化：只做AI的"提示词工程师"，忽视底层原理理解

建议定位​

短期（1-3年）：成为"AI配对程序员"，精通提示工程+代码审查，但更要深入业务
中期（3-5年）：进化为"领域架构师"，在某个垂直领域（医疗、金融、教育）建立AI无法替代的深度认知
长期：做"技术人类学家"，思考科技如何服务人性，而非让人类适应技术

最终，AI编程时代最好的定位是：保持人的主体性，让AI成为扩展你智慧的工具，而非定义你价值的主宰。代码可以被生成，但意义、判断与责任，永远需要人的肩膀来承担。

绝对需要，且比以往更关键。

AI编程时代，架构师不再是"搭架子"那么简单，而是成为 "AI的导航系统和刹车系统" 。没有架构师设定的框架，AI会像没有图纸的3D打印机——高效产出大量相互冲突的代码碎片。

为什么架子不可替代？​

1. AI的致命短板：缺乏系统级意图理解

• AI能完美实现"按用户ID查订单"，但无法理解"金融系统必须保证审计追踪与性能的平衡"
• 架构师的架子定义了质量属性（安全、性能、可扩展性）这些AI无法自行推导的约束条件

2. 技术债的复利效应

• 让100个AI Agent自由编码，3个月后得到的是一个"代码热带雨林"：茂密、复杂、充满未知依赖
• 架构师设的架子是债务控制的契约：服务边界、接口规范、数据流方向，防止AI在局部最优中陷入全局灾难

AI时代的"架子"新内涵​

传统架构师：画分层图 → 定技术栈 → 写开发规范
AI时代架构师：定义意图边界 → 建立AI可验证的约束 → 设计人机协作的治理流程

具体交付物：

• 意图描述层：用DSL或结构化Prompt定义"用户服务必须支持灰度发布"、"支付模块延迟小于50ms"，让AI在明确约束下生成
• AI可执行的架构契约：不是PDF文档，而是可自动校验的Schema、依赖规则、代码生成模板
• 风险防火墙：为AI划定禁区（如核心交易算法）、设置人类审查触发点（如涉及PII数据处理）
• 演化罗盘：定义系统演进的方向性原则（如"向事件驱动架构迁移"），防止AI短视优化

没有架构师的AI编程 = ？​

真实场景：

• 周一：10个开发用AI各生成10个微服务
• 周三：服务间调用关系变成蜘蛛网，发现5个AI选择了不兼容的序列化协议
• 周五：全团队停工，花3周时间重构——而架构师搭架子只要2天

数据印证： MIT 2024年研究显示，在无架构约束下使用AI编程，长期维护成本反比传统开发高40%——因为AI不理解"现在省事的方案为何未来会坑人"。

架构师的新操作范式​

不是画完图就交差，而是：

1. 意图编码：将架构决策转化为AI可理解的"元提示"(Meta-Prompt)
2. 动态调校：持续分析AI生成代码的架构漂移度，自动触发重构建议
3. 人机仲裁：当AI的优化建议与架构原则冲突时，做出基于业务生命周期的权衡

一句话总结​

AI是强大的工人，但架构师是唯一能看懂整个工地图纸、知道哪块砖会压垮未来的人。 在AI+软件工程中，架构师不搭架子，就等于让自动驾驶汽车在没有地图的原始森林里狂奔——速度越快，灾难越大。

AI+软件工程：人机协作的"四阶十二步法"

基于当前最佳实践，AI时代的软件工程流程应从人编码转向人定义、AI实现、人验证的意图驱动架构。这不是简单叠加AI工具，而是重构整个价值流。

核心原则：文档即代码，意图即架构​

关键转变：传统流程中代码是核心资产，新流程中结构化文档（Spec）成为驱动AI的"元代码"，代码退化为可再生的副产品。

阶段一：意图定义（人类主导）​

1. 需求精译与意图编码​

• 人类输出：不是PRD文档，而是 AI可执行的意图描述（结构化Markdown、DSL）
• 工具：用AI辅助需求分析，但人类必须定义验收标准的确定性约束（如"支付接口P99延迟 50ms"）
• 交付物：intent.md（业务目标）+ constraint.md（技术约束）

2. 架构契约设计​

• 人类输出：架构决策记录（ADR）+ AI可验证的架构约束Schema
• 关键动作：定义服务边界、接口契约、数据流方向，转化为AI能理解的治理规则（如"跨服务调用必须使用事件驱动"）
• 交付物：architecture-contract.json

3. 任务原子化拆解​

• 人类输出：将需求拆分为AI友好的单意图任务（每个任务可独立验证）
• 黄金法则：任务颗粒度 = 一个AI会话可完成的独立功能单元
• 交付物：tasks.md（带依赖关系的任务清单）

阶段二：AI实现（AI主导，人类监督）​

4. 上下文工程与知识注入​

• AI输入：任务 + 架构契约 + 相关领域知识库（RAG）
• 人类动作：构建项目的"数字记忆"——代码知识库、设计决策、历史Bug
• 工具：Context7、DeepWiki等上下文管理工具

5. 代码生成与自验证​

• AI动作：生成代码 + 自解释的验证逻辑（单元测试+集成测试草案）
• 人类干预点：关键算法、安全敏感代码必须人工Review，其他信任但需验证
• 交付物：代码 + 测试套件 + implementation-report.md（AI说明实现逻辑）

6. 持续集成与自动审查​

• 流程：代码提交 → AI自动Review（架构合规性、安全扫描）→ 人类抽查
• 关键：将架构契约转化为可执行的CI规则（如自动检测服务间循环依赖）
• 工具：AI增强的SonarQube、GitHub Copilot Workspace

阶段三：人机仲裁（人类决策）​

7. 架构漂移检测​

• 人类动作：每日运行架构健康度检查，对比生成代码与架构契约
• 工具：AI自动识别"代码实现是否偏离设计意图"，标记需要人工仲裁的冲突
• 输出：architecture-drift-report.md

8. 质量监护与伦理审查​

• 人类主导：AI无法覆盖的领域——业务正确性、伦理合规、用户体验
• 关键场景：金融风控规则、医疗诊断建议、用户隐私保护必须人工终审
• 流程：AI生成测试用例 → 人类补充边界案例 → AI执行验证

9. 意图校准循环​

• 触发条件：当AI输出与人类意图偏差>阈值时，启动意图重定义
• 动作：不是让AI重写代码，而是人类修正意图描述，让AI重新对齐
• 核心：问题永远在定义层，不在执行层

阶段四：演化治理（人机共管）​

10. 自动化文档同步​

• 机制：代码变更 → AI自动更新API文档、架构图、运维手册
• 原则：文档与代码单源真相，避免传统"代码实现已变，文档还是去年版本"
• 交付物：自动生成的docs/目录，与代码同版本管理

11. 预测性运维与自愈​

• AI动作：日志分析 → 故障预测 → 自动生成修复代码 → 人类审批后部署
• 人类角色：从"救火队员"转为风险决策者（批准AI的修复方案或否决不合理的建议）
• 工具：AI驱动的可观测性平台

12. 知识飞轮构建​

• 闭环：生产问题 → AI根因分析 → 更新知识库 → 优化下次代码生成
• 人类价值：标注高质量训练数据，建立领域专属的AI增强体系
• 终局：每个项目积累的数据成为组织的核心资产，而非代码

成熟度等级对照​

关键成功要素​

✅ 文档强制化：无文档不编码，无契约不生成
✅ 小步快跑：每个任务必须可独立验证，拒绝"AI一次性生成整个系统"
✅ 人类守住院线：架构、安全、伦理三大红线不可交由AI
✅ 工具链集成：让AI在CI/CD管道中无缝流转，而非孤立的聊天窗口

最终形态：这不是AI取代人的流程，而是人类从"手艺人"升级为"指挥家"，用意图和判断力驾驭AI的算力洪流。代码不再是资产，定义代码的意图体系才是未来最核心的技术资产。

微信公众号​