Metadata-Version: 2.1
Name: modao-prd-cli
Version: 0.2.0
Summary: Extract public Modao prototype shares into agent-friendly JSON, Markdown, and NDJSON
Author: modao-prd-cli contributors
License: MIT License
        
        Copyright (c) 2026 modao-prd-cli contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
        
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"

# 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
```

导出后，Agent 不需要把完整 `document.json` 一次性读入上下文。先查看轻量索引，再按关键词、页面或事实 ID 查询：

```bash
modao-prd-cli overview <project-id> --json
modao-prd-cli search <project-id> "奖励 概率" --json
modao-prd-cli screen <project-id> screen-001 --json
modao-prd-cli get <project-id> block-001 table-001 --json
modao-prd-cli unresolved <project-id> --json
```

`<project-id>` 可以是项目 ID，也可以是证据包目录。`search`、`screen` 和 `unresolved` 默认最多返回 20 条、约 30 KB，并提供 `truncated` 与 `next_cursor`；需要更多结果时使用 `--cursor` 或增大 `--max-bytes`。

不传 `--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
├── agent-index.json
├── search-index.sqlite
├── 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 → agent-index.json → coverage.json → search/get/screen → 必要时 document.json 或 evidence/`。

- `agent-index.json` 是面向 Agent 的轻量导航入口，只包含页面、表格、规则分类、交互摘要、覆盖率和警告，不替代事实。
- `search-index.sqlite` 是本地只读事实索引，包含所有可检索的 block、table、asset、状态、交互、规则和未覆盖项；查询不会访问网络，也不会把完整文档自动加载进上下文。
- `document.json` 使用 schema 2.1，是完整事实归档，区分 `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` 只作为分析线索。为了避免漏需求，不要用 `agent-index.json` 替代事实归档；应通过 `search` 定位后再用 `get` 读取原始事实。

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

## 限制

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

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