docs: clarify shared Python, CLI vs Action, and Task Center rules
All checks were successful
技能自动化发布 / release (push) Successful in 11s
All checks were successful
技能自动化发布 / release (push) Successful in 11s
This commit is contained in:
@@ -628,9 +628,18 @@ cmd_stats() # 只读 sync：JSON，无 job_context
|
||||
|
||||
### 1. 验证入口
|
||||
|
||||
本地验证请优先使用宿主共享 Python（与 Agent CLI 相同契约），例如：
|
||||
|
||||
```bash
|
||||
python scripts/main.py health
|
||||
python scripts/main.py version
|
||||
"$JIANGCHANG_PYTHON_EXE" scripts/main.py health
|
||||
"$JIANGCHANG_PYTHON_EXE" scripts/main.py version
|
||||
```
|
||||
|
||||
若环境已将共享 venv 置于 PATH，也可用 `python scripts/main.py …`。**禁止**对技能脚本使用 `uv run python`。
|
||||
|
||||
```bash
|
||||
python scripts/main.py -h
|
||||
python scripts/main.py <your-command> -h
|
||||
```
|
||||
|
||||
### 2. 验证 CLI 路由
|
||||
@@ -702,6 +711,8 @@ uses: client-jiangchang/jiangchang-platform-kit/.github/workflows/reusable-relea
|
||||
|
||||
在执行 `release.ps1` 之前，必须先在本地确认 `python tests/run_tests.py -v` 通过。测试不通过不得发起正式发布。
|
||||
|
||||
**发布前必须**将 `SKILL.md` 的 `version:` 与 `scripts/util/constants.py` 的 `SKILL_VERSION` 调整为将打出的版本（例如下一 patch），再执行 `release.ps1`。`release.ps1` **不会**自动改这两个字段；漏改会造成 git tag 与技能版本号不一致。
|
||||
|
||||
`release.ps1` 会在 **auto commit 之前**、推送 tag 之前，对**当前工作区**自动执行默认测试（`python tests/run_tests.py -v`）；失败则中止 release，不会留下失败状态的自动提交。仅紧急排障可使用 `-SkipTests` 跳过（会打印黄色警告）。`-DryRun` 预览发布时**仍会实际运行**默认测试，便于在不打 tag 的情况下验证门禁。
|
||||
|
||||
新增或调整开发规范时，须同步 [`development/POLICY_MATRIX.md`](POLICY_MATRIX.md) 与 [`tests/test_development_policy_guard.py`](../tests/test_development_policy_guard.py)（或注明由既有测试覆盖）。
|
||||
|
||||
@@ -7,6 +7,7 @@
|
||||
| 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（`JIANGCHANG_PYTHON_EXE` / python-runtime）；须明确**禁止**对技能脚本使用 `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-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` |
|
||||
|
||||
@@ -8,21 +8,24 @@
|
||||
|
||||
| 场景 | 推荐做法 |
|
||||
|------|----------|
|
||||
| 日常运行 | 由宿主匠厂触发技能 |
|
||||
| 手工排查 / 测试机 | 使用共享 runtime 的 `python.exe` 执行 `scripts/main.py` |
|
||||
| **不推荐** | 在技能目录内 `uv run python …` — 可能创建临时 venv，加载不到宿主共享 runtime |
|
||||
| 日常运行（宿主 / Agent） | 使用 `JIANGCHANG_PYTHON_EXE` 或 PATH 已指向的共享 venv `python` |
|
||||
| 手工排查 / 测试机（环境未注入时） | `{JIANGCHANG_DATA_ROOT}/python-runtime/.venv/.../python` 执行 `scripts/main.py` |
|
||||
| **禁止** | 在技能目录内 `uv run python …` — 会创建临时 venv，加载不到宿主共享 runtime |
|
||||
|
||||
占位命令（路径因环境而异，勿写死本机目录）：
|
||||
|
||||
```text
|
||||
Windows:
|
||||
推荐（已注入环境时）:
|
||||
"$JIANGCHANG_PYTHON_EXE" {baseDir}/scripts/main.py health
|
||||
|
||||
Windows（未注入时）:
|
||||
{JIANGCHANG_DATA_ROOT}\python-runtime\.venv\Scripts\python.exe {baseDir}\scripts\main.py health
|
||||
|
||||
通用:
|
||||
<shared-python> {baseDir}/scripts/main.py health
|
||||
Unix（未注入时）:
|
||||
{JIANGCHANG_DATA_ROOT}/python-runtime/.venv/bin/python3 {baseDir}/scripts/main.py health
|
||||
```
|
||||
|
||||
`<shared-python>` 通常位于 `{JIANGCHANG_DATA_ROOT}/python-runtime/.venv`。数据根由宿主注入；开发模式下也可能通过 `JIANGCHANG_DATA_ROOT` 解析（见 `jiangchang_skill_core.runtime_env`）。
|
||||
`<shared-python>` / `JIANGCHANG_PYTHON_EXE` 通常指向 `{JIANGCHANG_DATA_ROOT}/python-runtime/.venv`。数据根由宿主注入（见 `jiangchang_skill_core.runtime_env`）。
|
||||
|
||||
## Runtime 诊断（platform-kit 1.2.0+）
|
||||
|
||||
|
||||
@@ -20,8 +20,8 @@
|
||||
1. **宿主管调度，技能管业务** — 不自行实现任务中心 / Job 轮询 / 后台守护进程。
|
||||
2. **单业务内核、多入口** — 数据管理、定时任务、Agent、技能详情与直接 CLI 复用同一 domain service；禁止按入口复制业务逻辑。
|
||||
3. **五职责正交** — `placements` / `bind.tables` / `executionProfile` / `entrypoint` / domain service 各管一事（见 ACTIONS.md）。
|
||||
4. **长耗时建议 async** — 开浏览器、RPA、HTTP 大文件下载等建议 `executionProfile: "async"`，进**任务中心**；这是选择建议，**不**限制可以出现在哪些 placement。
|
||||
5. **Agent 禁止 `exec` 直跑长任务 CLI** — 必须 `run_skill_action`；禁止 `exec python main.py run` + `process poll` 干等。
|
||||
4. **长耗时建议 async** — 开浏览器、RPA、HTTP 大文件下载等建议 `executionProfile: "async"`，进**任务中心**；这是对**方法**的选择，**不**限制可以出现在哪些 placement / 入口。
|
||||
5. **Agent：短 CLI / 长 Action** — 短查询可用共享 Python bash CLI；长任务 / RPA **禁止** `exec` + `process poll`，必须 `run_skill_action`。
|
||||
6. **进度走 Journal** — `emit` / `video.add_step` → Run Journal；UI / Skill Run Card / 任务中心展示；**不靠 stdout 流**。
|
||||
7. **显式声明 `executionProfile`** — 每个 action **必须**写明 `sync` 或 `async`；禁止依赖宿主缺省；禁止第三种模糊模式（`auto` / `background` / `deferred` 等）。
|
||||
|
||||
@@ -160,15 +160,15 @@ cmd_stats() # 只读 sync：JSON stdout，无 job_context
|
||||
|
||||
## 8. Agent / SKILL.md 契约（复制后必改）
|
||||
|
||||
业务技能 `SKILL.md` 应明确：
|
||||
业务技能 `SKILL.md` / `references/` 应明确（Agent 主读，勿只写在本文）：
|
||||
|
||||
1. 副作用任务必须通过宿主 **Skill Action**（`run_skill_action`）调用。
|
||||
2. **禁止**对长任务使用 `exec` + `process poll`。
|
||||
1. 短查询：共享 Python（`JIANGCHANG_PYTHON_EXE`）跑 CLI；**禁止** `uv run`。
|
||||
2. 长任务 / RPA / async Action：必须通过宿主 **Skill Action**（`run_skill_action`）；**禁止** `exec` + `process poll`。
|
||||
3. 单条 vs 批量 action id 与参数（如 `url` / `pickCount`）。
|
||||
4. 长任务进度看**任务中心** / Skill Run Card，不等 CLI stdout。
|
||||
5. 多入口复用同一业务内核；异步 Action 进入任务中心。
|
||||
4. `executionProfile: async` → 进度看**任务中心** / Skill Run Card；`sync` → 当场结果。与入口无关。
|
||||
5. 多入口复用同一业务内核。
|
||||
|
||||
模板源仓库的 `SKILL.md` 含占位段落；scaffold 后按业务改写。
|
||||
模板源仓库的 `SKILL.md` / `references/ACTIONS.md` 含占位段落；scaffold 后按业务改写。
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user