docs: 修正 AGENT_RULES / AGENT_EVAL_GUIDE 中与 api_data / inputSchema 不符的 API 与代码#1
Open
2836603852 wants to merge 1 commit into
Open
docs: 修正 AGENT_RULES / AGENT_EVAL_GUIDE 中与 api_data / inputSchema 不符的 API 与代码#12836603852 wants to merge 1 commit into
2836603852 wants to merge 1 commit into
Conversation
…VAL_GUIDE
These docs get pasted into agent rules verbatim, so the bugs ship to every
AI coding against ascript-mcp. Each fix is verified against this repo's own
api_data/*.json, src/ascript_mcp/local.py inputSchemas, and device.py.
AGENT_EVAL_GUIDE.md (eval snippets A/C/F):
- Ocr.find_all() returns list[dict] (text/rect/center_x/center_y), not objects
with .text/.region_position -> AttributeError (C/F crash uncaught, A silently
drops OCR). Switch to dict keys. Evidence: android.json Ocr.find_all docstring
"Returns: list[dict]"; snippet D already uses r["center_x"].
- Snippet F node box used n.bounds ("# 假设有..."); real attr is
node.rect.left/top/right/bottom. Evidence: "bounds" absent from android.json.
AGENT_RULES.md:
- 3.5 "globals shared / don't re-import" -> fresh globals per call. Contradicts
AGENT_EVAL_GUIDE.md ("每次调用新建独立 globals") and device.py docstring
("请求级 fresh globals").
- search_api(keyword=) -> search_api(query=) [local.py inputSchema]
- get_code_example(scenario) -> (task, platform); get_plugin_detail(id) ->
(plugin_id) [local.py required inputSchema fields]
- Device.battery -> Device.battery() [android.json: staticmethod]
- Android Selector.className() -> .type() [android.json Selector has type, no className]
- iOS Selector.text() -> .label() [ios.json Selector has label/value/name, no text]
- 4.6 m.rect.x1 -> m.rect.left [node rect uses left/top/right/bottom]
- 3.1 drop invented constant MODE_ACC_FILTERED (only SIMPLE/ALL/ASS/ROOT exist)
All Python snippets in both docs still parse (ast.parse). Docs-only; no code change.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
背景
docs/AGENT_RULES.md与docs/AGENT_EVAL_GUIDE.md会被原样粘进 AI 的 agent rules，所以其中的 API / 代码错误会随每个用 ascript-mcp 的 AI 一起“出货”。本 PR 只改能用本仓库自己的源证伪（src/ascript_mcp/api_data/*.json、src/ascript_mcp/local.py的 inputSchema、src/ascript_mcp/device.py）的客观错误，纯文档、不动代码。两份文档里所有 Python 片段改后仍ast.parse通过。AGENT_EVAL_GUIDE.md（eval 片段）
Ocr.find_all()返回list[dict]（键text/rect/center_x/center_y），但片段按对象访问t.text/t.region_position.*→AttributeError（C、F 未捕获直接崩，A 被外层 try 吞成空 OCR，静默失效）。已改为 dict 取值android.json的Ocr.find_alldocstring：Returns: list[dict]；同文档片段 D 自己就用r["center_x"]（dict 取值），自相矛盾n.bounds（原注释即写# 假设有 left/top/right/bottom）；真实属性是node.rect.left/top/right/bottombounds在android.json中 0 命中AGENT_RULES.md
AGENT_EVAL_GUIDE.md（“每次调用新建独立 globals 字典 … 变量不会跨调用保留”）及device.pydocstring（“请求级 fresh globals”）一致；原 §3.5 与这两处直接矛盾search_api(keyword=)→search_api(query=)local.pysearch_apiinputSchema 必填字段是queryget_code_example(scenario)→(task, platform)local.pyinputSchemarequired: ["task","platform"]，无scenarioget_plugin_detail(id)→(plugin_id)local.pyinputSchemarequired: ["plugin_id"]Device.battery→Device.battery()android.jsonDevice.battery是staticmethod（漏括号会得到方法对象）Selector().className(...)→.type(...)android.jsonSelector 方法集有type、无classNameSelector().text(...)→.label(...)（Android.text()保留不动）ios.jsonSelector 字段是label/value/name/type、无textm.rect.x1/.y1/.x2/.y2→m.rect.left/.top/.right/.bottomleft/top/right/bottomMODE_ACC_FILTERED=2与“位掩码”说法，保留数字mode=2/3行为说明android.jsonSelector 常量只有MODE_ACC_SIMPLE/MODE_ACC_ALL/MODE_ASS/MODE_ROOT另外注意到（本 PR 未改，供参考）
search_api("intent"/"broadcast"/"ContentProvider")，但这些在android.json中不存在（0 命中）；真实间接通道是system.open/browser/open_app_setting/shell+shizuku。windows.json已是完整平台（window.Selector、原生Mouse/Keyboard、RapidOCR 等）。ios.json有action.click/Ocr.click（WDA 原生点击，仅“易被检测”）。以上三处更偏设计/措辞，留给维护者决定，本 PR 未改。
🤖 Generated with Claude Code