modao-prd-cli 0.1.0__tar.gz

modao_prd_cli-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+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.
+

modao_prd_cli-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+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)。

modao_prd_cli-0.1.0/README.md

@@ -0,0 +1,82 @@
+# 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)。

modao_prd_cli-0.1.0/modao_prd_cli/__init__.py

@@ -0,0 +1 @@
+"""Python package for the modao-prd-cli tool."""

modao_prd_cli-0.1.0/modao_prd_cli/modao_prd/__init__.py

@@ -0,0 +1,4 @@
+"""Public Modao prototype extraction CLI."""
+
+__version__ = "0.1.0"
+

modao_prd_cli-0.1.0/modao_prd_cli/modao_prd/__main__.py

@@ -0,0 +1,7 @@
+"""Run modao-prd-cli with ``python -m modao_prd_cli.modao_prd``."""
+
+from .cli import main
+
+
+if __name__ == "__main__":
+    main()