Metadata-Version: 2.4
Name: modao-prd-cli
Version: 0.1.0
Summary: Extract public Modao prototype shares into agent-friendly JSON, Markdown, and NDJSON
Author: modao-prd-cli contributors
License-Expression: MIT
Keywords: modao,prototype,prd,cli,agent,playwright
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click<9.0,>=8.1
Requires-Dist: playwright<2.0,>=1.62
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Dynamic: license-file

# modao-prd-cli

`modao-prd-cli` 将墨刀公开分享页采集为便于 Agent 读取的结构化文档和证据包。它使用本机 Chrome/Chromium 渲染页面，不登录墨刀、不保存 Cookie、不调用远程解析服务。

## 安装

```bash
python3 -m pip install modao-prd-cli
python3 -m playwright install chromium  # doctor 未发现可用浏览器时执行
modao-prd-cli doctor --json
```

## 使用

```bash
modao-prd-cli inspect "https://modao.cc/proto/<project-id>/sharing?view_mode=inspect" --json

modao-prd-cli export "https://modao.cc/proto/<project-id>/sharing?view_mode=inspect" \
  --format all
```

不传 `--output` 时，工具会从当前工作目录向上查找最近的 Git 根目录，并将结果写入该项目根目录下的 `.modao-prd/<project-id>/`。如果当前目录不属于 Git 项目，则使用当前工作目录作为项目根目录。首次默认导出会在项目根目录的 `.gitignore` 中幂等加入 `/.modao-prd/`。

如需指定其他位置，显式传入 `--output` 即可；此时不会修改项目的 `.gitignore`：

```bash
modao-prd-cli export "<墨刀公开分享链接>" \
  --format all --output ./modao-export
```

导出默认使用精简证据模式：保留结构化事实、DOM 布局快照、整页截图、可读画布截图和有效原型图片，过滤运行时代码、埋点资源和常见 UI 图标。DOM 快照也会排除 `script/style` 等运行时节点，避免把框架代码混进需求证据。需要排查渲染问题或核对视觉/无障碍细节时，再显式开启完整证据（debug/full）模式：

```bash
modao-prd-cli export "<墨刀公开分享链接>" --format all \
  --evidence full --headed --explore safe --max-states 50 --max-depth 3 \
  --max-actions 200 --timeout 30 --max-duration 120 \
  --max-item-mb 10 --max-total-mb 200
```

只支持 HTTPS 的墨刀公开分享路径：`https://modao.cc/proto/<project-id>/sharing`。

## 输出

```text
.modao-prd/<project-id>/
├── manifest.json
├── document.json
├── document.md
├── document.ndjson
├── coverage.json
└── evidence/
    ├── state-001.dom.json
    ├── state-001.screen-001.png          # essential/full：每个画布一张完整大图
    ├── state-001.full.png                # --evidence full
    ├── state-001.rendered.html            # --evidence full
    ├── state-001.aria.yaml               # --evidence full
    ├── assets/                           # 过滤后的原型图片
    └── network/                           # --evidence full
```

读取顺序建议为 `manifest.json → document.json → coverage.json → evidence/`。

- `document.json` 使用 schema 2.1，是面向 Agent 的紧凑精简投影，区分 `facts`（页面事实）和 `derived`（确定性启发式推导）；需要人读时使用 `document.md`，需要逐条检索时使用 `document.ndjson`。
- `document.md` 是人工阅读摘要，不替代原始证据。
- `document.ndjson` 是逐行知识单元，适合 RAG、向量化和增量处理。
- 默认精简模式输出 DOM/布局证据、可读画布截图和过滤后的原型图片；`--evidence full` 额外保存浏览器整页截图、渲染 HTML、ARIA、相关 JSON/HTML 网络正文和网络索引。精简模式不会为了“完整”保存无助于需求分析的浏览器整页截图、JS、CSS、埋点或通用图标。
- 每个画布默认只生成一张原始比例的完整大图，例如 `screen-001.png`，不再切分成多张图片；Agent 可按需放大图片，具体文本和结构优先从 `document.json`、`dom.json` 读取。
- `--headed` 只控制是否显示浏览器窗口，便于 debug，不会单独切换证据级别；完整证据必须显式指定 `--evidence full`。
- `coverage.json` 记录访问到的状态、动作、跳过项和部分完成原因。

`document.json` 不重复内嵌完整 DOM 父子关系，也不重复输出旧版的 `document.blocks`、顶层 `requirements`、`tables` 等别名；布局树保存在 `evidence/state-*.dom.json`，主文档通过状态和精简证据引用回查。所有页面事实尽量带 `state_id`、`screen_id` 和核心 `evidence_ids`。发生冲突时，以截图、HTML、DOM、ARIA 和原始表格为准；`derived` 只作为分析线索。

退出码为 `0`（在策略范围内完成）、`2`（得到可用但部分完成的证据包）、`1`（未得到可用文档）。

## 限制

- 不支持私有项目、登录态、评论和评审记录。
- 不点击抽奖、支付、购买、领取、提交、保存、发布、删除等高风险控件。
- 不访问页面中的外部链接；跨域 iframe、Canvas、视觉表格和图片文字只保存证据并标记未结构化区域。
- 不承诺理解业务语义；原型示例、日期、概率和外部文档引用需要人工确认。

Agent 使用说明见 [`skills/modao-prd-cli/SKILL.md`](skills/modao-prd-cli/SKILL.md)。
