cmsp/docs/04-local-development-and-verification.md

generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Local-Development-and-Verification wiki_url: https://git.ilapage.cn/chengma/cmsp/wiki/Local-Development-and-Verification.- wiki_revision: c539cdacdad897d81aee331d4d787e5a9f85a8cd synchronized_at: 2026-09-02T07:25:58Z

本地开发与验证

当前可执行范围

产品代码尚未建立。 目前本仓库只能执行文档结构检查与 Harness 自测。下面标注「计划」的命令在 Go 骨架建立前无法运行，建立后必须回到本页把它们改成经过实际运行验证的命令，并删除「计划」标注。

环境要求

依赖	版本	用途	当前是否必需
Python	3.10 及以上	运行 dev_scripts/harness.py 文档工具	是
Git	任意近期版本	版本管理	是
Go	1.22 及以上	编译后端	计划
Node.js	20 及以上	编译前端	计划
Wails CLI	v2 最新稳定版	构建桌面应用	计划
Google Chrome	近期稳定版	专属浏览器，登录淘宝并提供 CDP	计划
ffprobe	任意近期版本	校验下载的 MP4 是否完整	计划

运行环境为 Windows 10 及以上。不支持 macOS 与 Linux。

Windows PowerShell 与 UTF-8

• 优先使用当前已配置的 PowerShell；可选择时使用 PowerShell 7 pwsh.exe。
• 不要为了设置编码额外再启动一层 PowerShell。
• 文档与源码统一使用 UTF-8。命令支持时显式指定编码，例如 Get-Content -Encoding utf8。
• 只有确实出现乱码时才调整当前进程的输出编码，不要默认设置。
• 不使用 -ExecutionPolicy Bypass。确有可信 .ps1 被执行策略阻止且没有更小替代方案时，才对该次进程使用并在工单记录原因。

PowerShell 语法与外部命令

• Windows 环境默认使用当前 PowerShell 语法，不套用 Bash 的 heredoc、变量、路径、引号或反斜杠转义规则。只有明确调用 Bash、WSL 或 Git Bash，并确认路径与编码边界时，才使用 Bash 专用语法。
• 不需要变量展开的正则和字符串优先用单引号；单引号字符串内部的单引号写成两个单引号。需要变量展开时才使用双引号。
• 正则同时包含单双引号或转义复杂时，优先赋值给变量、使用 rg -e，或拆成语义等价的简单查询；不得为了避开转义改变 AND/OR 条件或重复执行无关搜索。

rg -n 'error|warning' docs
$pattern = 'can''t match "value"'
rg -n -e $pattern docs

PowerShell 不支持 Bash heredoc。需要把多行 Python 送入标准输入时，使用单引号 here-string，避免 PowerShell 展开 Python 中的 dollar sign（$）等内容。起始标记后必须立即换行，结束标记必须单独占一行：

@'
print("hello")
'@ | python -

foreach、if 等语句块不能裸放在管道左侧；需要管道输出时使用 $()、@() 或先赋值。普通命令输出无需包装：

@(foreach ($number in 1..3) { $number }) |
    Measure-Object

不要把含 * 的搜索路径直接作为 rg 路径参数。优先传入真实目录，并用 -g/--glob 让 ripgrep 筛选路径：

rg -n -g '*.md' 'PowerShell' docs

只有确实需要把实体路径列表交给其他命令时，才使用 Get-ChildItem 展开并传递 .FullName；不要把 Get-ChildItem -Filter 设为所有 rg 搜索的固定前置。

第一次运行

cd D:\chengma\cmsp
git status --short --branch
python dev_scripts/harness.py check --strict
python -m unittest discover -s tests -v

预期结果：

• git status 显示当前分支，且没有意料之外的改动。
• check --strict 输出检查通过，没有缺失文件或缺失章节。
• 单元测试全部通过。

如果 check --strict 报告镜像 revision 无效，说明 Wiki 尚未初始化或镜像未同步，按开发工作流的初始化门禁处理。

计划：构建与运行桌面应用

Go 骨架建立后补充，形式如下（尚未验证，不要直接复制使用）：

wails dev     # 开发模式，热重载
wails build   # 产出 Windows 可执行文件
go test ./... # 后端单元测试

常用调试方式

文档与流程

目的	命令	说明
检查文档结构	python dev_scripts/harness.py check --strict	检查必需文件与固定章节
快速核对 Wiki 镜像	python dev_scripts/harness.py sync --check	只比对 revision，不下载正文
完整核对镜像正文	python dev_scripts/harness.py sync --deep-check	怀疑镜像损坏时使用
导出镜像	python dev_scripts/harness.py sync	只能 Wiki → docs/，没有反向同步

计划：淘宝链路调试

Go 实现完成后适用：

• 专属 Chrome 是否就绪：访问 http://127.0.0.1:<端口>/json/version，能返回 JSON 即调试端口正常。
• 是否存在可用页面：访问 http://127.0.0.1:<端口>/json/list，检查是否有 type 为 page 的目标。
• 登录是否有效：在界面点击「检查登录状态」，看返回的缺失 Cookie 名称、页面标题与阻断词。
• 图搜是否成功：查看任务日志中的 HTTP 状态码与业务返回码，不要打印完整响应正文。

调试时禁止打印完整 Cookie、_m_h5_tk 完整值、账号密码和完整签名原文。

完成修改前

按顺序完成，缺一项就不算完成：

1. git status --short --branch 确认只包含本次任务相关文件。
2. 运行与改动范围相称的测试，并记录真实结果；没有跑到的部分明确写出未验证。
3. 判断是否有长期文档影响。有则先改 Gitea Wiki，读取确认，再 python dev_scripts/harness.py sync 导出镜像并检查差异；没有则记录原因。
4. python dev_scripts/harness.py check --strict 通过。
5. 提交只包含本次任务文件；有工单时提交信息带工单号，例如 feat: 商品列表分页 (#12)。
6. 有工单的任务在工单追加最终证据评论，状态置为「待验收」，等待人工验收。

涉及货憨憨写操作、账号凭据、SQLite 结构变更、并发或删除数据时，必须先确认再执行，不能靠试错获得风险反馈。