modao-prd-cli 0.1.0__tar.gz → 0.2.0__tar.gz

{modao_prd_cli-0.1.0/modao_prd_cli.egg-info → modao-prd-cli-0.2.0}/PKG-INFO

@@ -1,9 +1,31 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.1
 Name: modao-prd-cli
-Version: 0.1.0
+Version: 0.2.0
 Summary: Extract public Modao prototype shares into agent-friendly JSON, Markdown, and NDJSON
 Author: modao-prd-cli contributors
-License-Expression: MIT
+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
@@ -22,7 +44,6 @@ 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
 
@@ -45,6 +66,18 @@ modao-prd-cli export "https://modao.cc/proto/<project-id>/sharing?view_mode=insp
   --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`：
@@ -54,7 +87,7 @@ modao-prd-cli export "<墨刀公开分享链接>" \
   --format all --output ./modao-export
 ```
 
-导出默认使用精简证据模式：保留结构化事实、DOM 布局快照、整页截图、可读画布截图和有效原型图片，过滤运行时代码、埋点资源和常见 UI 图标。DOM 快照也会排除 `script/style` 等运行时节点，避免把框架代码混进需求证据。需要排查渲染问题或核对视觉/无障碍细节时，再显式开启完整证据（debug/full）模式：
+导出默认使用精简证据模式：保留结构化事实、DOM 布局快照、可读画布截图和有效原型图片，过滤运行时代码、埋点资源和常见 UI 图标。DOM 快照也会排除 `script/style` 等运行时节点，避免把框架代码混进需求证据。需要排查渲染问题或核对视觉/无障碍细节时，再显式开启完整证据（debug/full）模式：
 
 ```bash
 modao-prd-cli export "<墨刀公开分享链接>" --format all \
@@ -73,6 +106,8 @@ modao-prd-cli export "<墨刀公开分享链接>" --format all \
 ├── document.json
 ├── document.md
 ├── document.ndjson
+├── agent-index.json
+├── search-index.sqlite
 ├── coverage.json
 └── evidence/
     ├── state-001.dom.json
@@ -84,9 +119,11 @@ modao-prd-cli export "<墨刀公开分享链接>" --format all \
     └── network/                           # --evidence full
 ```
 
-读取顺序建议为 `manifest.json → document.json → coverage.json → evidence/`。
+读取顺序建议为 `manifest.json → agent-index.json → coverage.json → search/get/screen → 必要时 document.json 或 evidence/`。
 
-- `document.json` 使用 schema 2.1，是面向 Agent 的紧凑精简投影，区分 `facts`（页面事实）和 `derived`（确定性启发式推导）；需要人读时使用 `document.md`，需要逐条检索时使用 `document.ndjson`。
+- `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、埋点或通用图标。
@@ -94,7 +131,7 @@ modao-prd-cli export "<墨刀公开分享链接>" --format all \
 - `--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` 只作为分析线索。
+`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`（未得到可用文档）。
 

modao_prd_cli-0.1.0/PKG-INFO → modao-prd-cli-0.2.0/README.md

@@ -1,29 +1,3 @@
-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、不调用远程解析服务。
@@ -45,6 +19,18 @@ modao-prd-cli export "https://modao.cc/proto/<project-id>/sharing?view_mode=insp
   --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`：
@@ -54,7 +40,7 @@ modao-prd-cli export "<墨刀公开分享链接>" \
   --format all --output ./modao-export
 ```
 
-导出默认使用精简证据模式：保留结构化事实、DOM 布局快照、整页截图、可读画布截图和有效原型图片，过滤运行时代码、埋点资源和常见 UI 图标。DOM 快照也会排除 `script/style` 等运行时节点，避免把框架代码混进需求证据。需要排查渲染问题或核对视觉/无障碍细节时，再显式开启完整证据（debug/full）模式：
+导出默认使用精简证据模式：保留结构化事实、DOM 布局快照、可读画布截图和有效原型图片，过滤运行时代码、埋点资源和常见 UI 图标。DOM 快照也会排除 `script/style` 等运行时节点，避免把框架代码混进需求证据。需要排查渲染问题或核对视觉/无障碍细节时，再显式开启完整证据（debug/full）模式：
 
 ```bash
 modao-prd-cli export "<墨刀公开分享链接>" --format all \
@@ -73,6 +59,8 @@ modao-prd-cli export "<墨刀公开分享链接>" --format all \
 ├── document.json
 ├── document.md
 ├── document.ndjson
+├── agent-index.json
+├── search-index.sqlite
 ├── coverage.json
 └── evidence/
     ├── state-001.dom.json
@@ -84,9 +72,11 @@ modao-prd-cli export "<墨刀公开分享链接>" --format all \
     └── network/                           # --evidence full
 ```
 
-读取顺序建议为 `manifest.json → document.json → coverage.json → evidence/`。
+读取顺序建议为 `manifest.json → agent-index.json → coverage.json → search/get/screen → 必要时 document.json 或 evidence/`。
 
-- `document.json` 使用 schema 2.1，是面向 Agent 的紧凑精简投影，区分 `facts`（页面事实）和 `derived`（确定性启发式推导）；需要人读时使用 `document.md`，需要逐条检索时使用 `document.ndjson`。
+- `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、埋点或通用图标。
@@ -94,7 +84,7 @@ modao-prd-cli export "<墨刀公开分享链接>" --format all \
 - `--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` 只作为分析线索。
+`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`（未得到可用文档）。
 

{modao_prd_cli-0.1.0 → modao-prd-cli-0.2.0}/modao_prd_cli/modao_prd/__init__.py

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