19 KiB
19 KiB
开发规范 → 自动检测索引
本文件是 development/*.md 规范到机器检测的追溯表，不是另一份长规范。新增或调整 hard 规则时，须同步更新本矩阵与 tests/test_development_policy_guard.py（或注明已有测试覆盖）。
| policy_id | 规则摘要 | 来源 | 强制级别 | 自动检测 | 对应测试 |
|---|---|---|---|---|---|
| POLICY-STRUCTURE-001 | 标准 scripts/ 分层：main.py、cli/、service/、db/、util/ 必须存在 |
development/DEVELOPMENT.md §2 新 skill 的标准目录结构；development/RUNTIME.md §目录结构 | hard | 目录存在性检查 | tests/test_development_policy_guard.py::TestPolicyStructure001 |
| POLICY-RUNTIME-001 | 不得 vendored scripts/jiangchang_skill_core/ |
development/RUNTIME.md §共享 Python Runtime、§明确禁止 | hard | 目录不存在检查 | tests/test_development_policy_guard.py::TestPolicyRuntime001（另见 tests/test_platform_import.py） |
| POLICY-RUNTIME-002 | requirements.txt 非注释依赖行不得声明 jiangchang-platform-kit / playwright |
development/RUNTIME.md §共享 Python Runtime；development/DEVELOPMENT.md §3.1 requirements.txt 依赖规范 | hard | 解析依赖行 | tests/test_development_policy_guard.py::TestPolicyRuntime002（另见 tests/test_platform_import.py） |
| POLICY-RUNTIME-003 | Agent/CLI 文档须要求共享 Python（python-runtime / PATH 上的 python + {baseDir}）；须明确禁止对技能脚本使用 uv run python |
development/RUNTIME.md；references/CLI.md；SKILL.md | hard | 文档标记扫描 | tests/test_docs_standards.py::test_cli_md_requires_shared_python_not_uv_run；tests/test_docs_standards.py::test_skill_md_requires_shared_python_not_uv_run |
| POLICY-AGENT-001 | SKILL.md 须含「用户意图路由表」结构；CLI.md 须含短 CLI 白名单 / Action 强制黑名单表；用法回答须禁止无故粘贴 CLI、禁止为答用法列目录挖 references |
SKILL.md；references/CLI.md | hard | 文档标记扫描 | tests/test_docs_standards.py::test_skill_md_has_intent_routing_table；tests/test_docs_standards.py::test_cli_md_has_agent_routing_tables；tests/test_docs_standards.py::test_skill_md_how_to_forbids_cli_paste |
| POLICY-INSTALL-001 | 交付执行文件不得含 pip install / python -m pip install / uv pip install / playwright install |
development/RUNTIME.md §共享 Python Runtime；development/RPA.md §1.4 Playwright 与安装边界；development/DEVELOPMENT.md §3.1 | hard | 扫描 scripts/**/*.py、*.ps1、*.sh、requirements.txt、.github/workflows/*（不扫 development/*.md；根目录 sync.ps1 除外，它是开发者手动执行的本机同步，用 uv pip install 装进宿主共享 venv） |
tests/test_development_policy_guard.py::TestPolicyInstall001 |
| POLICY-CONFIG-001 | 仓库根目录必须存在 .env.example |
development/CONFIG.md §核心原则、§标准配置项 | hard | 文件存在性 | tests/test_development_policy_guard.py::TestPolicyConfig001 |
| POLICY-CONFIG-002 | .gitignore 必须忽略 .env 与 *.env.local |
development/CONFIG.md §红线：敏感信息不进 .env | hard | 解析 .gitignore 行 |
tests/test_development_policy_guard.py::TestPolicyConfig002 |
| POLICY-CONFIG-003 | 业务代码不得直接 os.environ / os.getenv / os.putenv / environ.get；须经 jiangchang_skill_core.config.get*（允许 main.py、测试、config_bootstrap/runtime 边界文件） |
development/CONFIG.md §配置 bootstrap；development/ADAPTER.md §档位 dispatch | hard | 扫描 scripts/**/*.py 并排除边界文件 |
tests/test_development_policy_guard.py::TestPolicyConfig003 |
| POLICY-CONFIG-004 | .env.example 每个活跃 KEY= 必须有中文行头（是什么）与中文行尾（怎么填）；注释禁止 development/、*.md 文档指向、account-manager、adapter 档位 等开发黑话 |
development/CONFIG.md §.env.example 注释 = 配置管理用户文案 | hard | 解析 .env.example 活跃行与注释 |
tests/test_development_policy_guard.py::TestPolicyConfig004 |
| POLICY-CONFIG-005 | 若 .env.example 使用 # @required，须单独占一行且在下一行中文行头之上；禁止写在行尾；禁止无中文行头或多 key 共用 |
development/CONFIG.md §必填项：# @required | hard | 解析 .env.example 活跃行与 @required 标记 |
tests/test_development_policy_guard.py::TestPolicyConfig005 |
| POLICY-TESTING-001 | 默认根目录 tests/test_*.py 不得硬编码 real_api / real_rpa / OPENCLAW_TEST_TARGET（白名单仅 test_adapter_profile_policy.py，用于档位 helper 自测） |
development/TESTING.md §默认必跑测试要做什么、§4 测试目标档位 | hard | 扫描 tests/test_*.py 非注释行；白名单外禁止上述文本 |
tests/test_development_policy_guard.py::TestPolicyTesting001 |
| POLICY-TESTING-002 | tests/integration/ 下 Python 测试文件若存在，默认应为 .sample，不得进入默认套件 |
development/TESTING.md §7 真实联调测试的安全约束、§8 新 skill 的最小测试清单 | hard | 检查 tests/integration/*.py 无 .sample 后缀 |
tests/test_development_policy_guard.py::TestPolicyTesting002 |
| POLICY-RPA-001 | 不得 import/use account-manager 内部 rpa_helpers / inject_account_manager_scripts_path / get_account_credential |
development/ADAPTER.md §兄弟依赖；development/RPA.md §1.7 | hard | 扫描 scripts/**/*.py 禁止模式 |
tests/test_development_policy_guard.py::TestPolicyRpa001（另见 tests/test_no_rpa_helpers_import.py） |
| POLICY-RPA-002 | RPA 交付代码不得直接执行 ffmpeg 拼 MP4；应使用 RpaVideoSession（允许 ffmpeg_path 等诊断字段） |
development/RPA.md §5.3 录屏成片标准 | hard | 扫描 scripts/**/*.py 禁止 subprocess / os.system / os.popen 直接调用 ffmpeg（task_run_support.py 保留豁免） |
tests/test_development_policy_guard.py::TestPolicyRpa002 |
| POLICY-RPA-003 | 即使默认 OPENCLAW_RECORD_VIDEO=0，RPA / 长任务模板也必须保留录屏能力：RpaVideoSession、video.add_step、video artifact merge 进 finish() 字段 |
development/RPA.md §5.3；development/LOGGING.md；development/CONFIG.md | hard | 扫描 scripts/service/*.py（service 层整体须含上述接入） |
tests/test_development_policy_guard.py::TestPolicyRpa003 |
| POLICY-RPA-004 | 网页 RPA：.env.example 若声明 OPENCLAW_BROWSER_HEADLESS 则默认必须为 0；scripts/ 若使用 launch_persistent_* 则必须同时存在 pick_web_account（先 Profile 再开浏览器；实现上应走 ensure-web）；登录不全局强制，但不得跳过 account-manager |
development/RPA.md §0.2；development/ADAPTER.md §兄弟依赖 | hard | 解析 .env.example + 扫描 scripts/**/*.py |
tests/test_development_policy_guard.py::TestPolicyRpa004 |
| POLICY-RPA-005 | 必须保留 AI + RPA 总纲，明确 Agent / RPA 职责、授权范围、禁止破解/逆向/私有协议/安全验证绕过、人工介入、状态等待；真实业务默认动作节奏为 1～3 秒 | development/AI_RPA.md §4–§6；development/RPA.md §0.0/§0.3 | hard（文档与默认配置） / soft（真实行为） | 检查总纲关键边界；解析 .env.example 的 STEP_DELAY_MIN=1.0 / STEP_DELAY_MAX=3.0 |
tests/test_development_policy_guard.py::TestPolicyRpa005 |
| POLICY-RPA-006 | 浏览器 RPA 必须保留 account-manager 生命周期标准；所有样例账号选择路径都须返回非空 profile_dir + lease_token，指定数字账号 ID 不得退化为无租约 account get |
development/ACCOUNT_MANAGER.md；development/ADAPTER.md §兄弟依赖；development/RPA.md §0.2 | hard | 检查标准文档关键标记；扫描真实/仿真 account_client.py 的指定 ID 带租约实现并禁止空租约赋值 |
tests/test_development_policy_guard.py::TestPolicyRpa006 |
| POLICY-PACKAGING-001 | scripts/**/*.py 单文件 < 1000 行 |
development/DEVELOPMENT.md §3.4 发布打包约束；development/RUNTIME.md §发布打包约束 | hard | 行数统计 | 已有测试覆盖：tests/test_release_packaging_constraints.py::test_scripts_py_files_under_pyarmor_line_limit |
| POLICY-PACKAGING-002 | 文本文件 UTF-8 without BOM，无 U+FEFF |
development/DEVELOPMENT.md §3.4；development/RUNTIME.md §编码与输出 | hard | BOM / 解码检查 | 已有测试覆盖：tests/test_release_packaging_constraints.py::test_text_files_are_utf8_without_bom |
| POLICY-RELEASE-001 | 发布 tag（去掉前缀）必须等于 SKILL.md 的 version: 且等于 scripts/util/constants.py 的 SKILL_VERSION；release.ps1 打 tag 前硬失败，不自动改写字段 |
development/DEVELOPMENT.md §15 发布；宿主市场「最新版本」来自 tag、「当前版本」来自包内 SKILL.md |
hard | release.ps1 门禁 + 日常版本字段对齐测试 |
release.ps1（Assert-SkillReleaseVersionAlignment）；tests/test_development_policy_guard.py::TestPolicyRelease001；tests/test_skill_metadata.py::test_skill_version_alignment |
| POLICY-DOCS-001 | 本矩阵存在且包含上述全部 policy_id |
本次规范化约定 | hard | 解析 development/POLICY_MATRIX.md |
tests/test_development_policy_guard.py::TestPolicyDocs001 |
| POLICY-LOGGING-001 | CLI 入口必须调用 setup_skill_logging |
development/LOGGING.md；development/RUNTIME.md | hard | 扫描 scripts/cli/app.py 含 setup_skill_logging 与 logger info |
tests/test_development_policy_guard.py::TestPolicyLogging001 |
| POLICY-LOGGING-002 | service 主任务入口必须使用 get_skill_logger |
development/LOGGING.md；development/DEVELOPMENT.md | hard | 扫描 scripts/service/task_service.py |
tests/test_development_policy_guard.py::TestPolicyLogging002 |
| POLICY-LOGGING-003 | 主任务入口须含 log.info/logger.info、log.exception/logger.exception |
development/LOGGING.md | hard | 扫描 scripts/service/task_service.py |
tests/test_development_policy_guard.py::TestPolicyLogging003 |
| POLICY-LOGGING-004 | 长任务 / RPA 模板须使用 Activity 或 RPA video step 输出进度 | development/LOGGING.md；development/RPA.md | hard | 扫描 scripts/service/task_service.py 含 emit( / activity.emit / video.add_step |
tests/test_development_policy_guard.py::TestPolicyLogging004 |
| POLICY-LOGGING-005 | 交付代码不得在 logging 调用行以 key=value 形式记录明显敏感字段 |
development/LOGGING.md；development/CONFIG.md | hard | 扫描 scripts/**/*.py 的 logging 调用行（不含注释） |
tests/test_development_policy_guard.py::TestPolicyLogging005 |
| POLICY-LOGGING-006 | scripts/service/**/*.py 业务域文件须有 `log/logger/_logger.(info |
warning | error | exception)；豁免薄工具：init.py、task_run_support.py、entitlement_service.py、sibling_bridge.py` |
development/LOGGING.md §0、§3 |
| POLICY-LOGGING-007 | 若 service 层含 RPA 标记（RpaVideoSession / uiautomation / playwright / rpa_step），则须出现事件词 task_start、task_failed 或 rpa_failed、以及 stage= |
development/LOGGING.md §3.1–§3.2 | hard | 合并扫描 scripts/service/**/*.py |
tests/test_development_policy_guard.py::TestPolicyLogging007 |
| POLICY-LOGGING-008 | scripts/service/**/*.py 中若 print 含 ERROR:，同一函数体内须有 `log/logger/_logger.(warning |
error | exception)` | development/LOGGING.md §0 铁律 3 | hard |
| POLICY-CONTROL-001 | 不得存在 scripts/util/progress.py 或自建 stdout 进度模块 |
development/LOGGING.md §2.5；development/RPA.md §0.1 | hard | 文件不存在检查 | tests/test_development_policy_guard.py::TestPolicyControl001 |
| POLICY-CONTROL-002 | task_service.py 须使用 job_context( 与 finish( |
development/LOGGING.md §2.5、§7 | hard | 扫描 scripts/service/task_service.py |
tests/test_development_policy_guard.py::TestPolicyControl002 |
| POLICY-CONTROL-003 | scripts/service/*.py 不得裸 asyncio.sleep（RPA 等待须 interruptible_sleep） |
development/RPA.md §0.1 | hard | 扫描 service 层 Python | tests/test_development_policy_guard.py::TestPolicyControl003 |
| POLICY-DATA-PATH-001 | 技能拥有路径须经 resolve_data_path / get_*_dir；.env.example 禁止 ./ CWD 相对路径；业务代码禁止 abspath(config.get(...)) |
development/DATA_PATHS.md | hard | 扫描 .env.example 与 scripts/**/*.py |
tests/test_development_policy_guard.py::TestPolicyDataPath001 |
| POLICY-SKILL-ACTION-001 | 存在 development/SKILL_ACTION_RUNTIME.md；schema 含 executionProfile；业务技能（非模板占位 slug）若 service 含 RpaVideoSession 则 actions.json 须有 executionProfile=async 且 placements 含 agent 的 action |
development/SKILL_ACTION_RUNTIME.md；references/ACTIONS.md | hard | 文档/schema/manifest 检查 | tests/test_development_policy_guard.py::TestPolicySkillAction001 |
| POLICY-SKILL-ACTION-002 | 每个 Action 必须显式声明 executionProfile，且只能是 sync 或 async |
development/SKILL_ACTION_RUNTIME.md；references/ACTIONS.md；assets/schemas/skill-actions.schema.json | hard | schema required + manifest 扫描 | tests/test_development_policy_guard.py::TestPolicySkillAction002；tests/test_actions_manifest.py |
| POLICY-SKILL-ACTION-003 | toolbar Action 必须声明合法非空 bind.tables（snake_case、唯一） |
references/ACTIONS.md；assets/schemas/skill-actions.schema.json | hard | schema if/then + manifest 扫描 | tests/test_development_policy_guard.py::TestPolicySkillAction003；tests/test_actions_manifest.py |
| POLICY-SKILL-ACTION-004 | placements 与 executionProfile 正交；文档不得把数据管理入口与异步执行方式硬绑定；Schema 须接受 toolbar/row/batch/cron/agent/skill-detail × sync/async 全部组合 |
development/SKILL_ACTION_RUNTIME.md；references/ACTIONS.md；assets/schemas/skill-actions.schema.json | hard | Schema 6×2 矩阵校验 + 文档禁止短语扫描 | tests/test_actions_manifest.py::test_schema_allows_all_placement_execution_profile_combinations；tests/test_development_policy_guard.py::TestPolicySkillAction004 |
| POLICY-TUTORIAL-001 | 存在 development/TUTORIAL_SURFACES.md；TUTORIAL.md 须含数据管理/对话/定时/对照表骨架；README.md 禁止「告诉 Agent」专章与入口专章；说明/教程正文禁止与页头重复的 # H1（主分节用 ##）；业务技能教程与 actions.json placements 对齐（无 cron 须声明不需要定时） |
development/TUTORIAL_SURFACES.md；development/CHECKLIST.md A2-7～A2-12 | hard | 文档存在性 + 章节/反模式扫描 + placements 对齐 | tests/test_tutorial_surfaces.py；tests/test_docs_standards.py::test_tutorial_surfaces_contract_doc_and_checklist |
| POLICY-ARCH-CORE-001 | 同一业务能力的 Action、CLI、Agent、cron、数据管理入口复用同一业务内核（文档要求已声明） | development/DEVELOPMENT.md；development/SKILL_ACTION_RUNTIME.md | hard（文档标记） / soft（语义） | 文档关键表述存在性；真实复用靠 sample/review | tests/test_development_policy_guard.py::TestPolicyArchCore001；tests/samples/test_action_core_contract.py.sample |
| POLICY-DATA-SYNC-001 | 同步型业务须遵循幂等、事务、完整性与空结果保护（文档已声明） | references/SCHEMA.md；development/SKILL_ACTION_RUNTIME.md | hard（文档标记） / soft（语义） | 文档关键表述存在性；完整语义靠 sample/review | tests/test_development_policy_guard.py::TestPolicyDataSync001；tests/samples/test_sync_contract.py.sample |
暂不自动检测（软规则）
以下规范仍须人工遵守或依赖 code review / AI 提示词 / sample 契约，不做成脆弱关键字扫描：
| 规则摘要 | 来源 | 原因 |
|---|---|---|
cli/ 只解析参数、不写业务逻辑 |
development/DEVELOPMENT.md §9 | 需语义理解，无法可靠静态判定 |
service/ 编排流向与模块拆分粒度 |
development/DEVELOPMENT.md §10 | 架构软约束；见 test_action_core_contract.py.sample |
| 是否真正复用同一业务内核 / 是否按 source 分叉 | development/SKILL_ACTION_RUNTIME.md §5 | 需调用图与人工审查 |
| 是否满足完整快照语义 / 空结果保护实现 | references/SCHEMA.md | 见 test_sync_contract.py.sample |
| 是否把系统导出与业务同步混淆 | references/ACTIONS.md；SCHEMA.md | 文档 + sample；勿做源码关键词误报扫描 |
db/ 层不得调浏览器或拼业务流程 |
development/DEVELOPMENT.md §11 | 需跨文件调用图 |
| slug 命名语义（动词-名词，平台可选） | development/NAMING.md | 部分覆盖于 tests/test_slug_naming.py，非本矩阵 hard policy |
复制模板不得保留 .git / template marker |
development/DEVELOPMENT.md §4 | 由 tests/test_scaffold_guard.py 守护，属脚手架场景 |
| 共享 runtime 导入来源非技能目录 | development/RUNTIME.md | 运行时依赖已安装包，见 tests/test_platform_import.py |
| RPA 真实轨迹、选择器纪律、状态等待、HITL 超时与有限重试是否正确实现 | development/AI_RPA.md；development/RPA.md §0–§1 | 文档和默认节奏已守护，真实行为与 DOM 质量仍需人工验收 |
| RPA 阶段日志是否「够细」（每个控件） | development/LOGGING.md §3.2 | hard 已要求里程碑事件词与域模块有日志；逐步粒度靠 sample 契约与验收 |
| adapter 四档契约测试覆盖 timeout/unauthorized 等 | development/ADAPTER.md §contract tests | 需业务实现后人工补测 |
SKILL.md / constants.SKILL_SLUG 一致性 |
development/DEVELOPMENT.md §16 | 已有 tests/test_skill_metadata.py |
| platform_kit_min_version >= 1.2.11 | development/RUNTIME.md | 已有 tests/test_platform_import.py |
宿主按 bind.tables 过滤 toolbar 按钮 |
references/ACTIONS.md | 待宿主升级后完整生效；模板侧已强制显式绑定 |
form +「已选择」时映射 readOnly 默认不占参数区（仍提交）；revealInForm 逃生阀 |
references/ACTIONS.md「选择摘要」 | soft（宿主 UX）；文档与 schema 已声明；勿用 visibleWhen 代替 |
数据管理技能按钮中文名（label）对照 ACTIONS.md 建议表；打开类成功静默 |
references/ACTIONS.md「Action 按钮中文名」 | 参考非白名单；行业词允许自创；勿做 label 关键字扫描 |
| Data Policy 未启用（L0）时宿主不得拉 Snapshot / 不得改按钮与行列行为 | references/POLICY.md | soft；宿主实现契约 |
| Data Policy 启用后 fail-closed（禁止回退 L0 全开）；写路径 domain 必须再鉴权 | references/POLICY.md §6–§7 | soft；POLICY-SKILL-AUTHZ-* 硬门禁可后续加 |
actions.mode 仅 allowlist/open；hostCapabilities 省略=不限制；scope valueFrom 仅 actor.userId |
references/POLICY.md §0.1 | soft；Schema 已约束 |