@succsoft/succapp 5.0.1 → 5.0.3

package/package.json

@@ -1,12 +1,8 @@
 {
 	"name": "@succsoft/succapp",
-	"version": "5.0.1",
+	"version": "5.0.3",
 	"description": "SuccApp CLI for AI-assisted low-code development, metadata workspace sync, and server automation.",
 	"license": "SEE LICENSE IN LICENSE",
-	"repository": {
-		"type": "git",
-		"url": "https://gitlab.succez.com/product/bi"
-	},
 	"bin": {
 		"succapp": "dist/cli/succapp.js"
 	},

package/resources/contents.properties

@@ -74,6 +74,8 @@ ustar:application/x-ustar
 src:application/x-wais-source
 xhtml:application/xhtml+xml
 xht:application/xhtml+xml
+atom:application/atom+xml
+rss:application/rss+xml
 zip:application/zip
 7z:application/x-7z-compressed
 gz:application/gzip
@@ -158,6 +160,7 @@ csv:text/csv
 wml:text/vnd.wap.wml
 wmls:text/vnd.wap.wmlscript
 etx:text/x-setext
+text:text/plain
 xsl:text/xml
 xml:text/xml
 mpeg:video/mpeg
@@ -181,6 +184,7 @@ ds:text/plain
 map:application/json
 json:application/json
 jsonc:application/json
+webmanifest:application/manifest+json
 schedule:text/xml
 page:text/html
 dfl:application/json
@@ -189,6 +193,9 @@ dmdl:application/json
 dtbl:application/json
 dtpt:application/json
 md:text/markdown
+markdown:text/markdown
+yaml:application/yaml
+yml:application/yaml
 tbl:application/json
 dash:application/json
 rpt:application/json
@@ -208,4 +215,4 @@ ctpl:application/json
 case:application/json
 meta:application/json
 jdbc:application/json
-spk:application/octet-stream
+spk:application/octet-stream

package/resources/workspace-templates/succapp-workspace/.agents/README.md

@@ -1,40 +1,19 @@
 # SuccApp AI 工作区
 
-本目录保存当前 SuccApp 工作区的 AI 共享上下文和 AI 协作产物。
+本目录保存 SuccApp 工作区里的 AI 协作规则和产物。开始修改业务内容前，先读工作区根目录的 `AGENTS.md`，再按任务需要阅读这里的规则或 skill。
 
-## 与主入口的关系
-
-`../AGENTS.md` 是常用 AI 工具优先读取的主入口。本文件补充工作区目录、AI 产物目录和本地
-运行态说明。修改内容前应先读 `../AGENTS.md`，再按需阅读本文件和 `rules/` 下的细则。
-
-## 工作区目录
-
-- 工作区根目录通常包含一个或多个从服务器克隆下来的元数据项目目录。
-- 项目文件是可编辑的交付内容，例如页面、报表、模型、脚本、扩展和配置等元数据文件。
-- `.meta` 文件保存每个资源的服务器标识、版本和元信息，是 SuccApp 同步和差异判断的重要依据。
-- `.succapp/` 保存本地服务器配置、镜像、缓存、锁、合并备份、日志和 IDE 辅助文件。
-
-更多修改安全边界见 `../AGENTS.md`。
-
-## 目录说明
+## 目录
 
 - `plans/`：实施计划、迁移计划和多步骤任务计划。
-- `reviews/`：Code Review、设计评审和变更评审。
-- `reports/`：调查报告、分析报告和验证报告。
+- `reviews/`：Code Review、设计评审和变更评审结果。
+- `reports/`：调查、分析、验证和排查报告。
 - `rules/`：团队长期维护的 AI 协作规则。
-- `skills/`：面向特定开发场景的 AI skill，例如 SuccBI 前端定制开发。
+- `skills/`：面向特定开发场景的 AI skill。`skills/succapp-docs/` 是 SuccApp CLI 同步的官方离线文档 skill。
 - `tmp/`：临时脚本、草稿和一次性排查文件。
 
-SuccApp 运行态文件保存在 `.succapp/` 下。`remote`、`cache`、`locks`、`merge-base`、
-`merge-backup`、日志文件和 `state.json` 都属于本地运行态。
-
-## AI 产物规则
+## 规则
 
-- 非简单任务的实施计划写到 `plans/`。
-- 评审结果写到 `reviews/`。
-- 调查、分析和验证总结写到 `reports/`。
-- 临时脚本和一次性草稿写到 `tmp/`。
-- 团队长期规则写到 `rules/`，不要只写在个人对话提示词里。
-- 可复用的场景化开发指南写到 `skills/`，并在任务命中时先阅读对应 `SKILL.md`。
-- `plans/`、`reviews/`、`reports/` 和 `tmp/` 默认忽略其中的文件。AI 产物需要长期保留时，
-  应先由人工确认，再调整忽略规则或移动到团队约定位置。
+- 计划、评审、报告和临时文件分别放入对应目录，不要散落在业务项目目录里。
+- 长期规则放入 `rules/`，可复用开发指南放入 `skills/`。
+- 官方 `skills/succapp-docs/` 是 SuccApp 产品用法和元数据规则的优先入口，由 SuccApp CLI 维护；团队补充内容放入 `rules/` 或其它自定义 skill。
+- `plans/`、`reviews/`、`reports/` 和 `tmp/` 默认忽略其中的文件；需要长期保留时先由人工确认。

package/resources/workspace-templates/succapp-workspace/.agents/gitignore.template

@@ -0,0 +1,2 @@
+tmp/
+

package/resources/workspace-templates/succapp-workspace/.agents/rules/workspace-rules.md

@@ -1,110 +1,39 @@
 # SuccApp 工作区规则
 
-本文件说明 SuccApp 初始化工作区后常见的目录结构、元数据识别规则和本地配置边界。AI 或人工修改工作区内容时，应先判断目标是否属于服务器元数据，再决定是否编辑、同步或推送。
+本文件只记录 SuccApp 工作区的本地安全边界。SuccApp 具体命令、页面/报表/模型/脚本/扩展开发、元数据格式和示例，以 `.agents/skills/succapp-docs/SKILL.md` 路由到的官方离线文档为准。
 
-## 目录结构
+## 元数据识别
 
-典型工作区结构如下，实际项目名称和业务目录会随服务器内容变化：
+判断一个文件是否属于服务器元数据，按这个顺序：
 
-```text
-<workspace-root>/
-|-- .meta                         # 根目录元数据索引，记录哪些一级目录是服务器元数据项目
-|-- <metadata-project>/            # 被根目录 .meta 记录的元数据项目，会参与 SuccApp 同步
-|   |-- .meta                      # 当前目录下直接子资源的元数据索引
-|   |-- <folder-or-file>           # 页面、报表、模型、脚本、扩展、配置等业务资源
-|   `-- <sub-folder>/
-|       |-- .meta                  # 子目录自己的资源索引
-|       `-- ...
-|-- .CKID/                         # 工作区或开发环境相关配置目录，通常不是业务元数据
-|   |-- ...                        # 连接、身份、环境、工具或历史兼容配置，按实际生成内容为准
-|-- .succapp/                      # SuccApp 本地运行态目录，不作为业务资源推送
-|   |-- config.json                # 服务器列表、当前激活服务器和同步相关配置
-|   |-- state.json                 # 本地同步状态、基线和项目状态
-|   |-- remote/                    # 服务器文件镜像，用于 diff、status、pull、push 的基线
-|   |-- cache/                     # 本地缓存
-|   |-- locks/                     # 同步写锁和任务锁
-|   |-- merge-base/                # 合并基线
-|   |-- merge-backup/              # 合并或覆盖前的备份
-|   |-- *.log                      # SuccApp 日志
-|   `-- tsconfig.*.json            # 脚本、浏览器端类型检查辅助配置
-|-- .agents/                       # AI 协作规则、计划、评审、报告和临时文件
-|   |-- README.md
-|   |-- rules/
-|   |-- plans/
-|   |-- reports/
-|   |-- reviews/
-|   `-- tmp/
-|-- .vscode/                       # VS Code 推荐设置和本地编辑器配置
-|-- tsconfig.json                  # 工作区 TypeScript 诊断入口
-|-- AGENTS.md                      # AI 工具主入口规则
-|-- CLAUDE.md                      # Claude 读取的工作区规则入口
-`-- .github/
-    `-- copilot-instructions.md    # GitHub Copilot 读取的工作区规则入口
-```
+1. 先看工作区根目录 `.meta`。根 `.meta` 记录的一层目录，才是 SuccApp 识别到的元数据项目。
+2. 再看目标文件父目录的 `.meta`。父目录 `.meta` 记录的子文件或子目录，才是该目录下的服务器元数据资源。
+3. 没有被对应 `.meta` 记录的内容，默认按本地辅助文件、临时文件或工具配置处理。
 
-重点判断顺序：
+## `.meta` 边界
 
-1. 先看工作区根目录 `.meta`。根目录 `.meta` 中记录的一层目录，才是 SuccApp 识别到的元数据项目目录。
-2. 再看目标文件所在父目录的 `.meta`。父目录 `.meta` 中记录的子文件或子目录，才是该目录下的服务器元数据资源。
-3. 没有被对应 `.meta` 记录的目录或文件，默认只是本地辅助内容、临时内容或工具配置，不会作为业务元数据推送到 BI 服务器。
+- `.meta` 是目录级资源索引，描述同目录下的直接子资源。
+- 修改业务文件前，应查看同目录 `.meta`，确认资源名称、ID、版本、类型、说明、排序等元信息。
+- 不要随意删除、重写、批量格式化 `.meta`，也不要制造空值、字段顺序、缩进等无意义差异。
+- 新增、删除或移动服务器元数据资源前，先读 `succapp-docs` 的相关任务文档，再参考相邻同类资源维护 `.meta`。
+- AI 计划、报告、评审、临时脚本、草稿和本地说明文件不要写入业务 `.meta`。
 
-## `.meta` 规则
+## 本地运行态
 
-- `.meta` 是目录级索引文件，内容描述同目录下的直接子资源，不描述 `.meta` 文件自身。
-- 根目录 `.meta` 用来标记哪些一级目录是元数据项目；未记录的一层目录不应当被当作服务器项目处理。
-- 项目内每级目录的 `.meta` 继续记录该目录下的业务文件和子目录。只有在父目录 `.meta` 里有条目的资源，SuccApp 才能把它和服务器资源建立同步关系。
-- 修改业务文件前，应同时查看同目录 `.meta`，确认资源名称、ID、版本、类型、说明、排序等元信息。
-- 不要随意删除、重写或格式化 `.meta`。无意义的字段顺序变化、空值变化和批量格式化会制造大量同步差异，影响人工评审。
-- 新增文件或目录时，如果它要成为服务器元数据资源，需要按现有同类资源和 SuccApp 同步规则维护对应父目录 `.meta`；如果只是本地说明、草稿、脚本或 AI 产物，不要写入 `.meta`。
-
-## `.succapp` 目录
-
-`.succapp/` 是 SuccApp 管理工作区时产生的本地运行态目录，重点用于连接服务器、保存同步基线、缓存远端文件和辅助编辑器诊断。
-
-- `config.json` 保存服务器地址列表、当前激活服务器和工作区同步配置。改动前应确认目标服务器和账号环境，避免把本地工作区指向错误环境。
-- `state.json` 保存本地同步状态、项目状态和基线信息。通常由 SuccApp 自动维护，不建议人工编辑。
-- `remote/` 是服务器文件镜像，不是用户直接维护的业务源码。它用于比较本地与远端差异，人工修改容易破坏 status、pull、push 判断。
-- `cache/`、`locks/`、`merge-base/`、`merge-backup/` 和日志文件都是本地运行态。除排查问题外，不作为任务交付内容修改。
-- `tsconfig.action.json`、`tsconfig.browser.json` 等用于脚本和浏览器端类型检查，属于编辑器辅助配置。
-
-## `.CKID` 目录
-
-`.CKID/` 常用于保存工作区、开发环境、历史兼容工具或产品侧生成的配置。它通常是本地配置目录，不是业务元数据项目。
-
-- 是否存在 `.CKID/`、里面有哪些文件，以当前工作区实际生成结果为准。
-- 修改 `.CKID/` 前先确认该配置由谁消费：SuccApp、VS Code、产品运行时、构建脚本还是历史工具。
-- 不要因为 `.CKID/` 位于工作区根目录，就把它当作会推送到 BI 服务器的元数据项目。是否推送仍以根目录 `.meta` 记录为准。
-- 如果 `.CKID/` 中的配置影响连接、身份、环境、构建或运行结果，修改后需要说明影响范围和建议验证方式。
-
-## 脚本开发规则
-
-SuccApp 工作区里的脚本通常也是元数据资源。修改页面脚本、扩展脚本、服务端动作脚本或临时排查脚本时，先判断脚本文件是否被同目录 `.meta` 记录，再按对应运行环境选择 API 和依赖。
-
-- 服务端动作脚本通常使用 `*.action.ts`，由 `.succapp/tsconfig.action.json` 提供本地诊断。它运行在服务端脚本环境，不要直接使用浏览器 DOM、浏览器 importmap 或前端组件库。
-- 浏览器端脚本、页面交互脚本和扩展前端脚本由 `.succapp/tsconfig.browser.json` 提供本地诊断。可以使用浏览器 API，但仍要以产品运行时实际提供的模块为准。
-- 编写 SuccBI 前端脚本前，优先查看产品包中的 `web/dist/succ-frontend-frameworks.json`。这份文件由 BI 构建脚本根据 `build-config.jsonc`、`importmap.json` 和 npm 包信息生成，用来说明运行时已内置、可通过 importmap 引入的前端依赖。
-- 如果 `succ-frontend-frameworks.json` 里已有合适依赖，优先使用清单中的 import specifier 和示例写法；不要仅凭通用 npm 经验新增依赖、改用未出现在清单或 importmap 中的包，或假设 Node.js 依赖能在浏览器端直接加载。
-- 关注清单条目的 `status`、`useFor`、`avoidFor`、`dependsOn`、`imports.js`、`imports.css` 和 `notes`。标记为 `legacy`、`internal` 或 `avoid` 的依赖，新功能不要主动采用，除非任务明确要求兼容历史实现。
-- 需要 CSS、Worker、地图资源、编辑器资源等附加入口时，按 `imports.css`、`imports.prefixes` 和 `notes` 处理，不要手写 dist 产物路径。
-- 临时验证脚本、一次性排查脚本和 AI 草稿应放在 `.agents/tmp/` 或团队约定的临时目录，不要写入业务 `.meta`；确实要沉淀为服务器资源时，再移动到元数据项目中并维护 `.meta`。
+- `.succapp/` 是 SuccApp 本地运行态目录，不是业务元数据目录。
+- `.succapp/config.json` 保存服务器配置，修改前必须确认目标服务器和账号环境。
+- `.succapp/state.json`、`remote/`、`cache/`、`locks/`、`merge-base/`、`merge-backup/` 和日志文件通常由 SuccApp 维护，除明确排查任务外不要人工编辑。
+- `.CKID/`、`.vscode/`、`tsconfig.json` 和 `.succapp/tsconfig.*.json` 通常是本地配置或编辑器辅助文件，不要仅因它们位于工作区根目录就当作服务器元数据处理。
 
 ## AI 协作目录
 
-`.agents/` 是 SuccApp 初始化项目设置时自动补齐的 AI 协作目录，用来放长期规则和协作产物，不属于业务元数据。
-
-- `rules/` 放团队长期规则，例如本文件。
-- `plans/` 放实施计划、迁移计划和多步骤任务计划。
-- `reports/` 放调查、分析和验证报告。
-- `reviews/` 放代码评审、设计评审和变更评审。
-- `tmp/` 放临时脚本、草稿和一次性排查文件。
-
-`plans/`、`reports/`、`reviews/` 和 `tmp/` 默认用于 AI 协作产物。是否提交到 Git、是否长期保留，由团队规则和人工确认决定。
+- `.agents/` 用来放 AI 协作规则和产物，不属于业务元数据。
+- `.agents/skills/succapp-docs/` 是 SuccApp CLI 同步的官方离线文档缓存，不直接手改。
+- 团队长期规则放 `.agents/rules/`；计划、报告、评审和临时文件分别放 `.agents/plans/`、`.agents/reports/`、`.agents/reviews/` 和 `.agents/tmp/`。
 
 ## 修改规范
 
-- 修改前先确认目标是否被对应 `.meta` 记录；被记录的资源按服务器元数据处理，未记录的内容按本地辅助文件处理。
-- 生产元数据改动应保持足够小，方便人工通过 Git diff 和 SuccApp Changes 视图评审。
-- 优先参考同目录、同类型资源的写法，不凭空发明新的元数据结构。
+- 改动范围保持小，方便人工通过 Git diff 和 SuccApp Changes 视图评审。
+- 优先参考官方离线文档、同目录 `.meta` 和同类型资源写法，不凭空发明元数据结构。
 - 未经人工明确确认，不要推送服务器、重置本地修改、覆盖冲突、删除资源或执行高风险 SQL。
-- 不要把 `.agents/`、`.vscode/`、`.succapp/`、`.CKID/` 或临时目录写入业务 `.meta`，除非已有明确产品规则要求它们成为服务器资源。
-- 修改完成后说明变更文件、是否涉及 `.meta`、是否需要推送服务器，以及建议验证步骤。
+- 修改完成后说明变更文件、是否涉及 `.meta`、是否需要服务器同步，以及建议验证步骤。

package/resources/workspace-templates/succapp-workspace/.succapp/gitignore.template

@@ -0,0 +1,9 @@
+# BEGIN SuccApp
+remote/
+cache/
+locks/
+merge-base/
+merge-backup/
+*.log
+state.json
+# END SuccApp

package/resources/workspace-templates/succapp-workspace/AGENTS.md

@@ -1,50 +1,33 @@
 # SuccApp 工作区 Agent 说明
 
-本工作区用于保存由 SuccApp 管理的元数据项目。SuccApp 是 SuccBI、SuccCI、SuccAP 配套的
-VS Code 扩展，支持元数据同步、脚本开发、扩展开发、Git 协作和 AI 辅助修改。
+本工作区保存由 SuccApp 管理的低代码元数据项目。AI 修改这里的内容时，优先把 `.agents/skills/succapp-docs/` 当作官方离线知识库；本文件只说明启动顺序和安全边界。
 
-## 产品上下文
+## 先读什么
 
-- SuccBI 是商业智能平台，面向数据接入、数据加工、仪表板、可视化分析、自助分析和报表场景。
-- SuccCI 是报表报送和数据采集平台，面向表单设计、填报、审批、上报和汇总流程。
-- SuccAP 是低代码应用平台，面向模型驱动的业务应用、页面、流程、权限和自定义交互。
-- SuccApp 操作的是这些产品的本地元数据文件。这里的修改仍需要人工评审、服务器验证、Git
-  评审和发布确认。
+修改任何内容前，按顺序读取：
 
-## 修改前必须读取
+1. `.agents/README.md`：AI 规则、计划、报告和临时文件的存放位置。
+2. `.agents/rules/workspace-rules.md`：`.meta`、`.succapp`、`.agents` 等本地安全边界。
+3. `.agents/skills/succapp-docs/SKILL.md`：SuccApp 官方离线文档入口。涉及页面、报表、模型、脚本、扩展、同步、命令或元数据结构时，必须按该 skill 的路由继续读取相关文档。
+4. `.agents/rules/` 下和当前任务相关的其它团队规则。
 
-修改任何内容前，先读：
+如果 `.agents/skills/succapp-docs/SKILL.md` 不存在，先提醒用户同步官方离线文档 skill。常用命令：
 
-1. 本文件。
-2. `.agents/README.md`：工作区目录、`.meta`、`.succapp` 运行态和 AI 产物位置说明。
-3. `.agents/rules/` 下和当前任务相关的细则。
+```bash
+succapp workspace init --scope agent-docs --force
+```
 
-如果任务涉及具体项目、页面、报表、模型、脚本或扩展，还要先查看相邻文件、同目录 `.meta`
-以及同类元数据写法，再开始修改。
+在 skill 修复前，不要凭通用经验编写 SuccApp 规则或元数据结构。
 
-## 工作区关键结构
+## 本地边界
 
-- 工作区根目录下的普通目录通常是从服务器克隆的元数据项目，例如页面、报表、模型、脚本和扩展等
-  交付内容。
-- 每个项目目录中通常包含 `.meta`。`.meta` 保存服务器资源标识、版本和目录下资源的元信息，是
-  SuccApp 同步和差异判断的重要依据。不要随意删除、重写或格式化 `.meta`。
-- `.succapp/config.json` 保存服务器地址列表和当前活跃服务器。
-- `.succapp/remote/`、`.succapp/cache/`、`.succapp/locks/`、`.succapp/merge-base/`、
-  `.succapp/merge-backup/`、`.succapp/*.log` 和 `.succapp/state.json` 是本地运行态文件，通常不应
-  作为业务内容修改或提交。
-- `.vscode/settings.json`、`tsconfig.json` 和 `.succapp/tsconfig.*.json` 是本地编辑器和脚本诊断辅助文件。
-- AI 计划、评审、报告和临时文件统一放在 `.agents/` 下，具体目录和忽略规则见 `.agents/README.md`。
-
-## 读取顺序
-
-这里是主入口。如果 `.agents/README.md` 或 `.agents/rules/` 中有更细的说明，以细则为准；但
-不要跳过本文件中的安全边界和 `.meta` 约束。
+- `.meta`、`.succapp/`、`.agents/` 和本地配置目录的具体边界见 `.agents/rules/workspace-rules.md`。
+- `.agents/skills/succapp-docs/` 由 SuccApp CLI 同步维护，默认作为官方文档缓存处理。团队规则、客户现场经验和项目约定写入 `.agents/rules/` 或其它自定义 skill，不直接修改官方文档缓存。
 
 ## 工作规则
 
-- 修改前先查看相关元数据文件、相邻 `.meta` 和当前 SuccApp 同步状态。
-- 改动范围应收敛到用户指定的项目、页面、报表、模型、脚本或扩展。
+- 修改业务资源前，先查看目标文件、相邻文件、同目录 `.meta` 和同类元数据写法。
+- 改动范围收敛到用户指定的项目、页面、报表、模型、脚本或扩展。
+- 新增、删除或移动服务器元数据资源前，先通过 `succapp-docs` 和相邻 `.meta` 确认规则。
 - 未经用户明确要求并确认目标环境，不要推送服务器、重置本地修改、覆盖冲突、删除元数据或执行高风险 SQL。
-- AI 计划、评审、报告和临时文件的目录规则以 `.agents/README.md` 为准。
-- 优先遵循现有项目约定和相邻元数据写法，不要凭空发明新结构。
-- 修改完成后说明变更文件和建议检查项。
+- 修改完成后说明变更文件、是否涉及 `.meta` 或服务器同步，以及建议检查项。

package/resources/workspace-templates/succapp-workspace/agent-workspace-template.jsonc

@@ -8,11 +8,9 @@
 		".agents/plans/.gitignore",
 		".agents/reports/.gitignore",
 		".agents/reviews/.gitignore",
-		".agents/rules/workspace-rules.md",
-		".agents/skills/succbi-frontend-development/SKILL.md"
+		".agents/rules/workspace-rules.md"
 	],
 	"directories": [
-		".agents/skills/succbi-frontend-development",
 		".agents/tmp"
 	]
 }

package/resources/workspace-templates/succapp-workspace/gitignore.template

@@ -0,0 +1,7 @@
+# BEGIN SuccApp local garbage
+.DS_Store
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+.agents/skills/succapp-docs/
+# END SuccApp local garbage

package/resources/workspace-templates/succapp-workspace/.agents/skills/succbi-frontend-development/SKILL.md

@@ -1,76 +0,0 @@
----
-name: succbi-frontend-development
-description: SuccBI 前端定制开发入口。修改 FTL、页面脚本、浏览器端脚本、CSS，或需要引入产品内置/第三方前端库时使用。
----
-
-# SuccBI 前端定制开发
-
-本 skill 用于在 SuccApp 工作区中修改 SuccBI 前端类元数据，例如 FTL 页面、浏览器端脚本、页面
-脚本、CSS、图片资源和随页面发布的第三方 JS/CSS 文件。
-
-## 开始前
-
-1. 先判断目标文件是否被同目录 `.meta` 记录。被记录的文件是服务器元数据资源，新增、删除或移动时
-   需要同步维护父目录 `.meta`。
-2. 查看同目录和相邻页面的写法，优先沿用已有目录结构、宏、样式命名和资源引用方式。
-3. 服务端动作脚本通常是 `*.action.ts`，运行在服务端脚本环境，不要在里面使用浏览器 DOM、FTL
-   页面资源或前端 importmap。
-
-## 使用产品内置前端库
-
-需要 React、ECharts、Three.js、地图、编辑器、UI 组件等前端能力时，先读取本目录下的
-`succ-frontend-frameworks.json`。
-
-- 优先使用清单中已有依赖，不要仅凭通用 npm 经验新增依赖或假设包名能在浏览器中直接 import。
-- 使用 `imports.js` 中的 specifier 写 JS/TS import。
-- 需要 CSS 时，使用 `imports.css` 中的 specifier 或清单 `notes` 中说明的资源入口。
-- 需要 worker、字体、地图资源或编辑器子资源时，先看 `imports.prefixes` 和 `notes`，不要手写
-  `/dist/node_modules/**` 产物路径。
-- `status` 为 `recommended` 的依赖可优先用于新功能；`legacy`、`internal` 或 `avoid` 的依赖只在
-  兼容历史代码或用户明确要求时使用。
-
-## 引入定制第三方前端库
-
-如果 `succ-frontend-frameworks.json` 中没有合适依赖，定制开发阶段可以把第三方前端库文件直接放到
-当前元数据目录或其子目录中，再用相对路径从 FTL 或页面资源引用。
-
-推荐结构：
-
-```text
-<page-or-ftl-dir>/
-|-- index.ftl
-|-- scripts/
-|   `-- page.js
-|-- styles/
-|   `-- site.css
-`-- vendor/
-    `-- some-lib/
-        |-- some-lib.min.js
-        `-- some-lib.min.css
-```
-
-FTL 中按相对路径引用：
-
-```html
-<link rel="stylesheet" href="./vendor/some-lib/some-lib.min.css">
-<link rel="stylesheet" href="./styles/site.css">
-<script src="./vendor/some-lib/some-lib.min.js"></script>
-<script src="./scripts/page.js"></script>
-```
-
-注意：
-
-- 不要在 SuccApp 元数据工作区里随意 `npm install`，也不要提交 `node_modules/`。
-- 第三方文件如果要随页面同步到服务器，必须按当前目录 `.meta` 的资源规则纳入元数据；只放本地但不
-  维护 `.meta`，通常不会成为可推送的业务资源。
-- 优先选择浏览器可直接运行的发行文件，例如 UMD/IIFE 或明确支持 `<script>` 的 ESM 文件；不要直接
-  拷贝只面向 Node.js 或构建器的源码包入口。
-- 保留第三方库的 license 文件或来源说明，方便后续人工评审和发布合规检查。
-
-## 修改 CSS 和页面脚本
-
-- CSS 优先沿用现有页面的 class 命名、变量和响应式断点，不做无关重排。
-- 页面脚本应只处理当前页面交互，不把服务端查询、权限判断或数据加工逻辑搬到浏览器端。
-- FTL 中已有 `<@useScript>`、`<@html>`、`<@head>`、`<@body>` 等宏时，按相邻文件模式使用，不要改成
-  独立 HTML 骨架。
-- 新增图片、字体、JS、CSS 等静态资源后，检查引用路径、大小写和 `.meta` 是否一致。