12 KiB
12 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-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） |
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-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 到 result_summary |
development/RPA.md §5.3；development/LOGGING.md；development/CONFIG.md | hard | 扫描 scripts/service/*.py（service 层整体须含上述接入） |
tests/test_development_policy_guard.py::TestPolicyRpa003 |
| 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-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，并写入 save_task_log |
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-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/cron/agent/skill-detail × sync/async 全部组合 |
development/SKILL_ACTION_RUNTIME.md；references/ACTIONS.md；assets/schemas/skill-actions.schema.json | hard | Schema 4×2 矩阵校验 + 文档禁止短语扫描 | tests/test_actions_manifest.py::test_schema_allows_all_placement_execution_profile_combinations；tests/test_development_policy_guard.py::TestPolicySkillAction004 |
| 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 命名语义（verb-noun-platform） | 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/RPA.md §0–§1 | 行为与 DOM 质量，无法静态扫描 |
| 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.0 | development/RUNTIME.md | 已有 tests/test_platform_import.py |
宿主按 bind.tables 过滤 toolbar 按钮 |
references/ACTIONS.md | 待宿主升级后完整生效；模板侧已强制显式绑定 |