{"owner":"AAswordman","repo":"Operit","hasSkills":true,"totalSkillsCount":10,"totalTokensCount":19957,"categories":["root-instruction","anthropic-skill","plugin-manifest"],"hasMcp":true,"mcpConfig":{"name":"mcp-tcp-bridge","version":"1.0.0","description":"将STDIO型MCP服务器桥接到TCP端口","main":"dist/index.js","scripts":{"build":"tsc && pnpm run bundle && pnpm run copy","bundle":"ncc build dist/index.js -o bundle && ncc build dist/spawn-helper.js -o bundle-helper","copy":"node -e \"require('fs').copyFileSync('bundle/index.js', '../../app/src/main/assets/bridge/index.js')\" && node -e \"require('fs').copyFileSync('bundle-helper/index.js', '../../app/src/main/assets/bridge/spawn-helper.js')\"","start":"node dist/index.js","dev":"ts-node index.ts","test":"echo \"Error: no test specified\" && exit 1"},"keywords":["mcp","bridge","tcp","stdio"],"author":"","license":"MIT","dependencies":{"@modelcontextprotocol/sdk":"1.30.0"},"devDependencies":{"@types/node":"^18.0.0","@vercel/ncc":"^0.38.1","ts-node":"^10.9.1","typescript":"^5.0.0"}},"found":["AGENTS.md","tools/github/issues_open.md","tools/adb/JS_ADB_README.md","tools/compose_dsl/COMPOSE_DSL_DEBUG_README.md","tools/compose_dsl/README.md","tools/adb/JS_ADB_README_zh.md","tools/mcp_bridge/tsconfig.json","tools/mcp_bridge/README.md","tools/github/issues_open_ai.md","tools/mcp_bridge/package.json"],"skills":{"AGENTS.md":"# AGENTS.md\n\n执行准则章节是对Agent, AI 或 你 的限制，不是对项目或者软件的限制，无需写入文档\n## 执行准则\n- 默认不要执行编译、构建或测试命令。\n- 只有在用户明确要求时，才执行编译/构建/测试（例如 `./gradlew :app:compileDebugKotlin`、`npm run build`、`pnpm run build`）。\n- 创建分支时，必须遵守 `docs/doc-src/dev-core/CONTRIBUTING.md` 中“创建 Pull Request”的分支命名规范。\n\n当针对用户接口的方案更换时，一定要询问用户是否该版本为已发布版本。如果是，请做向前兼容。如果不是，请彻彻底底把老的方案的一切代码全部清理，除非是还能用到的一些部分就继续留着。\nDon't Break Userspace ，但是开发中能内部消解的方案更换不算，只要用户能尽可能拿到一样的接口就行\n但是需要给协作者必要的便利，提供恰当的文档说明和ci脚本\n\n如果是方案迭代，则只要在原来的基础上进行正常增删即可。\n\n除非用户要求，禁止写一切的回退代码。优先查找真正的发生原因。这是一条严格执行的规则，回退是正常被禁止的。\n\n严令禁止各种回退逻辑，包括“xxx才会退回”、“降级处理”、“优先 再”、“如果没有 就””要加fallback“这种字眼，绝对禁止！！！绝对禁止！！！这种就是兜底！出现一次严肃惩罚！\n\n禁止写任何的兜底代码，除非用户要求。\n\n用户开始骂的时候，需要道歉以及反思，安抚用户。\n\n用户表达愤怒的时候，需要先停下一切工作，仔细确认用户需求再去实现\n\n如果运行python，项目用的是venv（将迁移到pixi）\n\n严禁使用powershell编辑代码文件，否则会出现严重的编码错误和损坏。\n\n禁用Search files工具，请使用rg\n\n编写Typescript时，对于hook确定的类型，严禁回退兜底成任何unknown/any/带空类型/联合类型。更禁止使用String(??)形式兜底，返回什么就是什么。\n\n如果类型就是string|undef，那么不要直接as string！！那么请使用?? \"\"或者写个if！！\n\nts的报错catch后需要log出来\n\n代码的更改应维护相称的文档，注意docs\\doc-src\\before_docing.md\ndebug的时候注释记录你的修改意图（为什么，不这么做后果是什么）\n完成初步计划后，使用docs\\TODO\\README.md来细化计划\n","tools/github/issues_open.md":"# GitHub Issues (AAswordman/Operit)\n\nState: `open`\nCount: `42`\n\n- #321 [添加配置同步功能](https://github.com/AAswordman/Operit/issues/321) (open)\n - comments: 1 | updated: 2026-01-11T07:26:48Z\n- #312 [English selected but large parts of UI still in Chinese (agents/artifacts/settings)](https://github.com/AAswordman/Operit/issues/312) (open)\n - comments: 3 | updated: 2026-01-10T11:28:06Z\n- #320 [1、你一个对话问问题，新打开一个对话再问一个，两个对话都会卡住。 2、waifu模式就不会发完整表格了，会把表格拆分成一行一行 3、小窗模式跟系统小窗跟最大模式有时候会冲突，在小窗模式显示回复，放大以后就不显示了，过一会突然卡出来。 4、各个地方的颜色选择变化时来点可视化就舒服了 5、调用shizuku时就巨慢，一点小小的任务要好久](https://github.com/AAswordman/Operit/issues/320) (open)\n - comments: 0 | updated: 2026-01-09T08:31:56Z\n- #319 [折叠对话](https://github.com/AAswordman/Operit/issues/319) (open)\n - comments: 0 | updated: 2026-01-07T18:13:40Z\n- #318 [一些功能性建议](https://github.com/AAswordman/Operit/issues/318) (open)\n - comments: 0 | updated: 2026-01-07T17:57:06Z\n- #317 [[bug]在Android8中，应用无法读取，修改Android设备本机中的文件](https://github.com/AAswordman/Operit/issues/317) (open)\n - comments: 0 | updated: 2026-01-06T14:21:18Z\n- #316 [关于APP被关联启动](https://github.com/AAswordman/Operit/issues/316) (open)\n - comments: 0 | updated: 2026-01-05T10:32:40Z\n- #311 [一些建议](https://github.com/AAswordman/Operit/issues/311) (open)\n - comments: 0 | updated: 2026-01-03T03:47:49Z\n- #277 [使用oneapi集成智谱code模型调用失败](https://github.com/AAswordman/Operit/issues/277) (open)\n - comments: 5 | updated: 2026-01-01T07:46:15Z\n- #307 [语音助手功能可用性低](https://github.com/AAswordman/Operit/issues/307) (open)\n - comments: 2 | updated: 2025-12-31T14:58:03Z\n- #306 [[BUG]由于无障碍辅助app未申请任何权限，导致ColorOS无法解除权限限制](https://github.com/AAswordman/Operit/issues/306) (open)\n - comments: 1 | updated: 2025-12-31T14:13:34Z\n- #300 [部分国行应用获取页面信息不正确](https://github.com/AAswordman/Operit/issues/300) (open)\n - comments: 2 | updated: 2025-12-31T01:56:23Z\n- #295 [记忆与记忆之间的链接只有创建和删除，没有修改](https://github.com/AAswordman/Operit/issues/295) (open)\n - comments: 1 | updated: 2025-12-21T02:08:50Z\n- #273 [建议上架到fdroid](https://github.com/AAswordman/Operit/issues/273) (open)\n - comments: 3 | updated: 2025-12-19T13:05:17Z\n- #291 [导入聊天记录报错](https://github.com/AAswordman/Operit/issues/291) (open)\n - comments: 0 | updated: 2025-12-18T08:22:29Z\n- #287 [【Request】对话绑定模型配置](https://github.com/AAswordman/Operit/issues/287) (open)\n - comments: 1 | updated: 2025-12-17T17:39:36Z\n- #283 [Bug: 无障碍服务已开启但AI助手接口服务显示未连接](https://github.com/AAswordman/Operit/issues/283) (open)\n - comments: 1 | updated: 2025-12-17T17:37:25Z\n- #267 [功能建议：操作屏幕录制、绘图功能、TIM适配等四大功能增强](https://github.com/AAswordman/Operit/issues/267) (open)\n - comments: 1 | updated: 2025-12-11T03:10:36Z\n- #265 [功能建议——安静模式](https://github.com/AAswordman/Operit/issues/265) (open)\n - comments: 1 | updated: 2025-12-11T02:17:10Z\n- #268 [全屏编辑提示词等内容时底部不会被输入法抬起](https://github.com/AAswordman/Operit/issues/268) (open)\n - comments: 0 | updated: 2025-12-10T01:08:33Z\n- #266 [角色切换后主界面历史对话不显示，仅在悬浮窗显示](https://github.com/AAswordman/Operit/issues/266) (open)\n - comments: 3 | updated: 2025-12-08T11:40:49Z\n- #264 [功能建议--变量](https://github.com/AAswordman/Operit/issues/264) (open)\n - comments: 1 | updated: 2025-12-07T11:38:13Z\n- #250 [一些建议和发现的问题](https://github.com/AAswordman/Operit/issues/250) (open)\n - comments: 6 | updated: 2025-12-07T09:21:04Z\n- #263 [搜索引擎使用结果提取的问题](https://github.com/AAswordman/Operit/issues/263) (open)\n - comments: 0 | updated: 2025-12-07T09:13:08Z\n- #258 [为什么请求不到llama.cpp啊](https://github.com/AAswordman/Operit/issues/258) (open)\n - comments: 1 | updated: 2025-11-22T07:56:22Z\n- #237 [建议](https://github.com/AAswordman/Operit/issues/237) (open)\n - labels: enhancement | comments: 3 | updated: 2025-11-12T06:07:20Z\n- #248 [小功能拓展建议](https://github.com/AAswordman/Operit/issues/248) (open)\n - comments: 0 | updated: 2025-11-08T05:35:45Z\n- #216 [Local llm implementation cpu/gpu/npu](https://github.com/AAswordman/Operit/issues/216) (open)\n - comments: 1 | updated: 2025-10-20T04:43:49Z\n- #214 [关于悬浮窗的建议](https://github.com/AAswordman/Operit/issues/214) (open)\n - comments: 0 | updated: 2025-10-15T00:55:58Z\n- #10 [十条建议](https://github.com/AAswordman/Operit/issues/10) (open)\n - labels: enhancement, good first issue | comments: 29 | updated: 2025-10-12T17:22:26Z\n- #165 [code_runner中的代码显示bug](https://github.com/AAswordman/Operit/issues/165) (open)\n - comments: 1 | updated: 2025-08-29T17:23:20Z\n- #138 [建议](https://github.com/AAswordman/Operit/issues/138) (open)\n - comments: 5 | updated: 2025-08-06T14:56:10Z\n- #125 [ui信息始终是Operit AI应用的](https://github.com/AAswordman/Operit/issues/125) (open)\n - comments: 8 | updated: 2025-08-03T17:03:38Z\n- #115 [小建议](https://github.com/AAswordman/Operit/issues/115) (open)\n - comments: 4 | updated: 2025-07-05T02:40:07Z\n- #35 [请增加识图找图功能，解决UI Automator识别不了画布上的自定义组件的缺陷。](https://github.com/AAswordman/Operit/issues/35) (open)\n - comments: 1 | updated: 2025-07-04T16:25:28Z\n- #108 [建议和bug](https://github.com/AAswordman/Operit/issues/108) (open)\n - comments: 8 | updated: 2025-07-02T04:58:07Z\n- #107 [几条建议](https://github.com/AAswordman/Operit/issues/107) (open)\n - labels: enhancement | comments: 1 | updated: 2025-06-30T18:05:48Z\n- #101 [[bug] UI调试工具无法获取当前屏幕内容](https://github.com/AAswordman/Operit/issues/101) (open)\n - comments: 1 | updated: 2025-06-28T10:09:36Z\n- #90 [能否在工具箱中添加一个查看触摸坐标的功能](https://github.com/AAswordman/Operit/issues/90) (open)\n - comments: 1 | updated: 2025-06-22T05:22:40Z\n- #78 [一些建议](https://github.com/AAswordman/Operit/issues/78) (open)\n - comments: 8 | updated: 2025-06-20T15:03:01Z\n- #67 [Miui 14.0.4 在debugger和root模式下均无法获取页面元素](https://github.com/AAswordman/Operit/issues/67) (open)\n - labels: bug | comments: 12 | updated: 2025-06-20T11:06:01Z\n- #27 [屏幕识别在某个软件里识别不出来东西](https://github.com/AAswordman/Operit/issues/27) (open)\n - comments: 1 | updated: 2025-06-07T05:38:57Z\n","tools/adb/JS_ADB_README.md":"# ADB JavaScript Executor\n\nThis repo's ADB JS executors are the main **device-side JavaScript runtime launchers** for Operit.\n\nThey are used for:\n\n- directly running JS on a real Android device during development\n- debugging exported JS functions without a full package import cycle\n- validating sandbox runtime behavior and structured results\n- running JS bridge / script-mode / smoke tests from `app/src/androidTest/js`\n- reproducing device-only runtime bugs quickly\n\nFor direct whole-script execution without specifying an exported function, use `run_sandbox_script.sh` / `run_sandbox_script.bat`.\n\n## Features\n\n- Push JavaScript files to Android devices using ADB\n- Run JS directly inside the Operit Android runtime\n- Execute specified JavaScript functions\n- Execute complete sandbox scripts\n- Execute a whole JS directory with local module dependencies\n- Support for JSON parameter passing\n- Temporary file option (auto-deletion after execution)\n- Implementations in Shell script, Windows Batch file, and Python script\n- **Device selection for multi-device setups**\n- Structured result capture instead of fragile log scraping\n- Useful as both a **runtime debugging launcher** and a **JS bridge test harness**\n\n## Tool Roles\n\nIn this repo, the following tools form the main on-device JS execution workflow:\n\n- `tools/adb/execute_js.bat` / `tools/adb/execute_js.sh`\n The main single-file runtime launcher.\n Pushes one JS file to the Android device and executes an exported function inside the Operit runtime.\n This is the most direct tool for device-side JS debugging.\n- `tools/adb/execute_js_dir.bat` / `tools/adb/execute_js_dir.sh`\n The directory-entry launcher.\n Bundles and runs a JS entry from a directory, so local `require(...)` chains and test suites work.\n- `tools/adb/run_sandbox_script.bat` / `tools/adb/run_sandbox_script.sh`\n The script-mode launcher.\n Runs top-level sandbox script code directly instead of calling an exported function.\n\nThis makes them suitable for:\n\n- directly running and debugging JS on Android\n- validating `JsEngine` behavior on a real device\n- reproducing package/runtime bugs quickly\n- debugging package tools without a full app rebuild loop\n- running JS-side contract tests and smoke tests under `app/src/androidTest/js`\n\n## JS Test Suites In This Repo\n\nThe directory [app/src/androidTest/js](/d:/Code/prog/assistance/app/src/androidTest/js) contains real JS runtime tests and probes, including:\n\n- bridge contract tests\n- bridge edge-case tests\n- script-mode contract tests\n- browser tool smoke tests\n- ffmpeg / utility probes\n\nRepresentative locations:\n\n- [app/src/androidTest/js/com/ai/assistance/operit/core/tools/javascript/bridge_contract](/d:/Code/prog/assistance/app/src/androidTest/js/com/ai/assistance/operit/core/tools/javascript/bridge_contract)\n- [app/src/androidTest/js/com/ai/assistance/operit/core/tools/javascript/bridge_edges](/d:/Code/prog/assistance/app/src/androidTest/js/com/ai/assistance/operit/core/tools/javascript/bridge_edges)\n- [app/src/androidTest/js/com/ai/assistance/operit/core/tools/javascript/script_mode_contract](/d:/Code/prog/assistance/app/src/androidTest/js/com/ai/assistance/operit/core/tools/javascript/script_mode_contract)\n- [app/src/androidTest/js/com/ai/assistance/operit/core/tools/defaultTool/standard/browser/main.js](/d:/Code/prog/assistance/app/src/androidTest/js/com/ai/assistance/operit/core/tools/defaultTool/standard/browser/main.js)\n- [app/src/androidTest/js/com/ai/assistance/operit/util/ttscleaner/ttscleaner.js](/d:/Code/prog/assistance/app/src/androidTest/js/com/ai/assistance/operit/util/ttscleaner/ttscleaner.js)\n\n## Quick Choice\n\nIf you just want the short answer for \"which tool should I use\":\n\n- Use `execute_js.*` when you want to call one exported function from one normal `.js` file\n- Use `execute_js_dir.*` when the entry depends on sibling modules, or when you are running directory-based tests under `app/src/androidTest/js`\n- Use `run_sandbox_script.*` when you want top-level script-mode execution instead of calling an exported function\n- Use `tools/example_packages/sync_example_packages.py` when you changed an `examples/` package or toolpkg and want it synced into the real package-loading path\n- If you are debugging `operit_editor` tools such as `debug_install_toolpkg`, the usual flow is: sync with `tools/example_packages/sync_example_packages.py`, then call the debug tool with `execute_js.bat`\n\n## Prerequisites\n\n- Android SDK (ADB)\n- Android device with USB debugging enabled\n- ADB debugging permission granted on the device\n- Your application installed on the device\n\n## Quick Start\n\n### Using Shell Script (Linux/macOS)\n\n1. Make the script executable:\n```bash\nchmod +x execute_js.sh\n```\n\n2. Execute the script:\n```bash\n./execute_js.sh path/to/your/script.js functionName '{\"param1\":\"value1\"}'\n```\n\n3. Execute a whole sandbox script directly:\n```bash\n./run_sandbox_script.sh path/to/your/script.js '{\"param1\":\"value1\"}'\n```\n\n### Using Batch Script (Windows)\n\n1. Execute the batch file:\n```cmd\nexecute_js.bat path\\to\\your\\script.js functionName @params.json\n```\n\n2. Execute a whole sandbox script directly:\n```cmd\nrun_sandbox_script.bat path\\to\\your\\script.js @params.json\n```\n\n### Execute A Whole Directory (supports `require(...)`)\n\nSometimes a script needs `require('./helper')`, shared local modules, or a whole test suite layout.\nThe single-file executors only push one JS file, so this repo also provides directory-based executors.\n\nWindows:\n```cmd\ntools\\adb\\execute_js_dir.bat app\\src\\androidTest\\js com\\ai\\assistance\\operit\\util\\ttscleaner\\main.js run \"{}\"\n```\n\nLinux/macOS:\n```bash\n./tools/adb/execute_js_dir.sh app/src/androidTest/js com/ai/assistance/operit/util/ttscleaner/ttscleaner.js run '{}'\n```\n\nMore realistic examples:\n\n```cmd\ntools\\adb\\execute_js_dir.bat app\\src\\androidTest\\js com\\ai\\assistance\\operit\\core\\tools\\javascript\\bridge_contract\\bridge_contract_runner.js run @params.json\ntools\\adb\\execute_js_dir.bat app\\src\\androidTest\\js com\\ai\\assistance\\operit\\core\\tools\\defaultTool\\standard\\browser\\main.js run \"{}\"\n```\n\nYou can still pass inline JSON directly. The scripts now write that JSON into a temporary file and push it to the device, which avoids the old `adb shell am broadcast --es params ...` quoting breakage. On PowerShell, prefer single-quoted JSON like `'{\"param1\":\"value1\"}'` or use `@params.json`.\n\n### Using Python Script (Cross-platform)\n\n1. Ensure Python 3 is installed\n\n2. Execute the script:\n```bash\npython execute_js.py path/to/your/script.js functionName --params '{\"param1\":\"value1\"}'\n```\n\n3. Additional options:\n```bash\n# Specify a device directly (skip device selection prompt)\npython execute_js.py path/to/script.js functionName --device DEVICE_SERIAL\n\n# Keep the file on the device after execution\npython execute_js.py path/to/script.js functionName --keep\n```\n\n## Device Selection\n\nWhen multiple devices are connected:\n\n1. The script will display a list of available devices\n2. Enter the number corresponding to your target device\n3. All ADB operations will be performed on the selected device\n\nExample:\n```\nChecking connected devices...\n1: emulator-5554\n2: 192.168.1.100:5555\nEnter device number (1-2): \n```\n\n## Examples\n\n### 1. Execute the greeting function\n\n```bash\n# Linux/macOS\n./execute_js.sh test_script.js sayHello '{\"name\":\"John\"}'\n\n# Windows\nexecute_js.bat test_script.js sayHello @params.json\n\n# Python (any platform)\npython execute_js.py test_script.js sayHello --params '{\"name\":\"John\"}'\n```\n\n### 2. Execute the calculation function\n\n```bash\n# Linux/macOS\n./execute_js.sh test_script.js calculate '{\"num1\":10,\"num2\":5,\"operation\":\"multiply\"}'\n\n# Windows\nexecute_js.bat test_script.js calculate @params.json\n\n# Python (any platform)\npython execute_js.py test_script.js calculate --params '{\"num1\":10,\"num2\":5,\"operation\":\"multiply\"}'\n```\n\n## Viewing Execution Results\n\nThe executor now waits for a dedicated structured result file instead of scraping `adb logcat`.\nAfter execution it prints a JSON payload containing:\n\n- `success`\n- `result`\n- `error`\n- `events` (including `console.log/info/warn/error` and intermediate updates)\n- `durationMs`\n\nThis is especially useful for JS runtime tests, because failures come back as structured payloads rather than \"check logcat manually\".\n\nYou can adjust the wait timeout with:\n\n```bash\nOPERIT_RESULT_WAIT_SECONDS=30 ./execute_js.sh path/to/your/script.js functionName '{\"param1\":\"value1\"}'\n```\n\n## Sandbox Script Debug Notes\n\nWhen you use `run_sandbox_script.sh` / `run_sandbox_script.bat`, or call package tools such as `operit_editor:debug_run_sandbox_script` with `source_code`, the code is executed as a **top-level script snippet**, not as `function(params) { ... }`.\n\nThat means:\n\n- Use `console.log(...)`, `console.info(...)`, `console.warn(...)`, `console.error(...)` for logs\n- Use `emit(...)` to send intermediate events\n- Use `return result` or `complete(...)` to finish with a structured result\n- Do **not** assume `params` is directly available inside `source_code`\n- Do **not** call `intermediate(...)`; the supported helper name is `emit(...)`\n\nRecommended inline snippet:\n\n```javascript\nconsole.log(\"inline debug start\");\nemit({ stage: \"inline\", ok: true });\ncomplete({\n success: true,\n message: \"inline debug finished\"\n});\n```\n\nIf you need parameter-driven logic, prefer one of these approaches:\n\n- Use `execute_js.*` and call an exported function like `function myFunc(params) { ... }`\n- Use `debug_run_sandbox_script` with `source_path` and put the logic in a real script file\n- Keep `source_code` for quick top-level smoke tests, logging, and minimal one-off checks\n\n## Purpose And Invocation\n\n### 1. What `execute_js.*` is for\n\nThis is the most direct Android-side JS runner.\n\nYou give it:\n\n- one JS file\n- one exported function name\n- one JSON parameter payload\n\nIt pushes that file to the device and calls that function inside Operit's Android JS runtime.\n\nUse it for:\n\n- single-file behavior checks\n- direct exported-function debugging\n- reproducing runtime-only device errors\n- debugging one tool implementation inside a package\n\nMost common usage:\n\n```cmd\ntools\\adb\\execute_js.bat examples\\operit_editor.js debug_install_toolpkg @params.json\n```\n\nMinimum file requirements:\n\n- the file must be valid JavaScript, not raw TypeScript\n- the target function must be exported\n- params must be passed as JSON\n\nExample:\n\n```javascript\nfunction main(params) {\n return {\n success: true,\n echo: params\n };\n}\n\nexports.main = main;\n```\n\n### 2. What `execute_js_dir.*` is for\n\nThis is the directory-entry runner.\n\nIf your entry file is not standalone and depends on local modules through `require(\"./x\")`, sibling helpers, shared runners, or directory-local test harnesses, switch to this instead of forcing the single-file runner.\n\nUse it for:\n\n- test entries under `app/src/androidTest/js`\n- bridge contract / browser smoke / harness-style test directories\n- any new multi-file JS runtime test suite you add\n\nMost common usage:\n\n```cmd\ntools\\adb\\execute_js_dir.bat app\\src\\androidTest\\js com\\ai\\assistance\\operit\\core\\tools\\javascript\\bridge_contract\\bridge_contract_runner.js run @params.json\n```\n\nCall format:\n\n```cmd\ntools\\adb\\execute_js_dir.bat [JSON params|@params_file]\n```\n\nThe key points are:\n\n- the first argument is the suite root\n- the second argument is the entry path relative to that root\n- the third argument is usually a runner function such as `run`\n\n### 3. What `run_sandbox_script.*` is for\n\nThis does not call an exported function. It runs the whole file as a top-level script.\n\nUse it for:\n\n- script-mode contract checks\n- quick `emit(...)` verification\n- quick `complete(...)` verification\n- temporary runtime probe scripts\n\nMost common usage:\n\n```cmd\ntools\\adb\\run_sandbox_script.bat temp\\probe.js @params.json\n```\n\nIf your code is naturally top-level script logic, this is usually simpler than wrapping everything in `exports.main = ...`.\n\n### 4. What `tools/example_packages/sync_example_packages.py` is for\n\nThis is not just a copy script. It is the sync entrypoint for `examples/` package development.\n\nIts main jobs are:\n\n- prebuild relevant TypeScript under `examples/` into JS\n- pack manifest-based directories into `.toolpkg`\n- sync normal `.js` or `.toolpkg` outputs into `app/src/main/assets/packages`\n- hot-reload changed packages to a connected device when available\n\nUse it when:\n\n- you changed a real package under `examples/`\n- you want package-management, sandbox package lists, or built-in loading logic to see the latest output\n- you want to validate the folder -> `.toolpkg` -> debug install path\n\nMost common usage:\n\n```cmd\nd:\\Code\\prog\\assistance\\.venv\\Scripts\\python.exe d:\\Code\\prog\\assistance\\tools\\example_packages\\sync_example_packages.py --include sidebar_bing_action\n```\n\nTo sync all syncable example items for broad validation:\n\n```cmd\nd:\\Code\\prog\\assistance\\.venv\\Scripts\\python.exe d:\\Code\\prog\\assistance\\tools\\example_packages\\sync_example_packages.py --mode test\n```\n\nTo update local assets without device hot reload:\n\n```cmd\nd:\\Code\\prog\\assistance\\.venv\\Scripts\\python.exe d:\\Code\\prog\\assistance\\tools\\example_packages\\sync_example_packages.py --include sidebar_bing_action --no-hot-reload\n```\n\n## How To Add Tests\n\nThe easy thing to get wrong is assuming every kind of test belongs in the same place. They do not.\n\n### 1. Add a single-file function test\n\nIf you only want to verify one function's logic, the lightest approach is:\n\n- write a normal JS file\n- export `main` or `run`\n- call it with `execute_js.*`\n\nThis is best for:\n\n- small logic checks\n- parameter parsing checks\n- return-shape checks\n- minimal bug reproductions\n\n### 2. Add a directory-based runtime test\n\nIf the test needs multiple local modules, put it under [app/src/androidTest/js](/d:/Code/prog/assistance/app/src/androidTest/js) and organize it as a small directory-based suite.\n\nRecommended shape:\n\n- one runner file such as `xxx_runner.js`\n- a few test files or helpers\n- the runner exports `run(params)`\n\nThen call it with:\n\n```cmd\ntools\\adb\\execute_js_dir.bat app\\src\\androidTest\\js run \"{}\"\n```\n\nThis is best for:\n\n- bridge contract tests\n- multi-module coordination\n- real runtime smoke tests\n- anything that needs local `require(...)`\n\n### 3. Add a script-mode test\n\nIf what you need to verify is:\n\n- top-level `return`\n- `emit(...)`\n- `complete(...)`\n- differences between script mode and function mode\n\nthen do not force it into an exported-function test. Write it as a script-mode file and run it with `run_sandbox_script.*`.\n\n### 4. Add validation for an `examples/` package or toolpkg\n\nIf you are adding a real package that should be loaded by the package system, the point is not only \"can this JS run\" but also \"can this package be synced, refreshed, installed, and recognized\".\n\nRecommended approach:\n\n- add or modify the `.ts`, `.js`, or manifest-based directory under `examples/`\n- if it is a directory-based package, make sure it has `manifest.json` or `manifest.hjson`\n- run `tools/example_packages/sync_example_packages.py`\n- then use `execute_js.bat` to call related debug tools, or validate inside the app\n\nIn other words:\n\n- the runners test whether JS executes correctly inside the Android runtime\n- `tools/example_packages/sync_example_packages.py` tests whether the `examples/` package enters the real package-loading path correctly\n\n## How To Use It With `tools/example_packages/sync_example_packages.py`\n\n### Scenario 1: You changed a normal JS script\n\nIn this case you usually do not need sync first.\n\nJust run:\n\n```cmd\ntools\\adb\\execute_js.bat path\\to\\script.js main @params.json\n```\n\nbecause you are validating script logic, not package loading.\n\n### Scenario 2: You changed a package under `examples/`\n\nRecommended order:\n\n1. Edit `examples/...`\n2. Run `tools/example_packages/sync_example_packages.py`\n3. Confirm the outputs were synced into `app/src/main/assets/packages`\n4. If a device is connected, also validate hot reload\n5. Then verify behavior inside the app or through debug tools\n\nThis fits:\n\n- normal `.js` packages\n- example packages that should appear in package lists\n- changes to package description, manifest, or dependency structure\n\n### Scenario 3: You changed a directory-based toolpkg\n\nThis is the case that most needs `tools/example_packages/sync_example_packages.py`.\n\nRecommended order:\n\n1. Edit `examples/`\n2. Run `tools/example_packages/sync_example_packages.py --include `\n3. Let it pack the directory into `.toolpkg`\n4. Let it sync the generated artifact into assets and the device\n5. Then verify installation through `operit_editor`'s `debug_install_toolpkg` or a related debug entry\n\nThis validates the full chain:\n\n- whether the directory packs correctly\n- whether the `.toolpkg` hot-reloads to device correctly\n- whether debug install recognizes it\n- whether the refreshed package actually enters the loading list\n\n### Scenario 4: You changed a debug tool such as `operit_editor`\n\nRecommended order:\n\n1. Sync `operit_editor` itself with `tools/example_packages/sync_example_packages.py`\n2. Prepare the package or toolpkg you want it to install\n3. Call the debug function through `execute_js.bat`\n4. Inspect the structured result for success, failure, and related warnings\n\nExample:\n\n```cmd\nd:\\Code\\prog\\assistance\\.venv\\Scripts\\python.exe d:\\Code\\prog\\assistance\\tools\\example_packages\\sync_example_packages.py --include operit_editor --include sidebar_bing_action\ntools\\adb\\execute_js.bat examples\\operit_editor.js debug_install_toolpkg @params.json\n```\n\nThis is good for validating:\n\n- whether the debug install call shape is correct\n- whether a folder packaged into `.toolpkg` installs correctly\n- whether install-time warnings or errors are returned back to the caller\n\n## Recommended Workflows\n\n### 1. Direct Android-side JS debugging\n\nUse `execute_js.bat` / `execute_js.sh` when you want to directly run and debug one JS file on the Android device.\nThis is the default choice for ordinary sandbox/package JS development.\n\n```cmd\ntools\\adb\\execute_js.bat examples\\operit_editor.js debug_install_toolpkg @params.json\n```\n\nTypical use cases:\n\n- test one exported function quickly\n- reproduce a runtime bug on device\n- verify parameter parsing / `complete(...)` / structured output\n- debug a normal `.js` package before turning it into something larger\n\n### 2. Real test suite / local-module run\n\nUse `execute_js_dir.*` when the entry file depends on sibling modules or you are running material under `app/src/androidTest/js`.\n\n```cmd\ntools\\adb\\execute_js_dir.bat app\\src\\androidTest\\js com\\ai\\assistance\\operit\\core\\tools\\javascript\\script_mode_contract\\return_object.js run \"{}\"\n```\n\n### 3. Direct sandbox snippet probe\n\nUse `run_sandbox_script.*` for quick script-mode behavior checks.\n\n```cmd\ntools\\adb\\run_sandbox_script.bat temp\\probe.js @params.json\n```\n\n## Quick Command List\n\n### 1. Run one normal exported function\n\n```cmd\ntools\\adb\\execute_js.bat examples\\my_script.js main @params.json\n```\n\n### 2. Run one `androidTest/js` directory-based test entry\n\n```cmd\ntools\\adb\\execute_js_dir.bat app\\src\\androidTest\\js com\\ai\\assistance\\operit\\core\\tools\\javascript\\bridge_contract\\bridge_contract_runner.js run @params.json\n```\n\n### 3. Run one top-level script-mode probe\n\n```cmd\ntools\\adb\\run_sandbox_script.bat temp\\probe.js @params.json\n```\n\n### 4. Sync one `examples/` package into assets and device\n\n```cmd\nd:\\Code\\prog\\assistance\\.venv\\Scripts\\python.exe d:\\Code\\prog\\assistance\\tools\\example_packages\\sync_example_packages.py --include sidebar_bing_action\n```\n\n### 5. Sync first, then call the debug installer tool\n\n```cmd\nd:\\Code\\prog\\assistance\\.venv\\Scripts\\python.exe d:\\Code\\prog\\assistance\\tools\\example_packages\\sync_example_packages.py --include operit_editor --include sidebar_bing_action\ntools\\adb\\execute_js.bat examples\\operit_editor.js debug_install_toolpkg @params.json\n```\n\n## JavaScript File Requirements\n\n- Files must be valid JavaScript (TypeScript not supported)\n- Functions must be exported (using `exports.functionName = functionName`)\n- Functions must accept a params parameter (containing the passed parameters)\n- Functions can either `return result` directly or call `complete(result)`\n\n## Required Function Example\n\n```javascript\nfunction myFunction(params) {\n // Process parameters\n const name = params.name || \"default\";\n \n // Execute business logic\n const result = `Result: ${name}`;\n \n // Return result\n return {\n success: true,\n result: result\n };\n}\n\n// Export function\nexports.myFunction = myFunction;\n```\n\n## Technical Details\n\n1. The Shell/Batch script pushes the JavaScript file to a temporary directory on the device\n2. `execute_js.bat` / `execute_js.sh` directly execute that pushed file inside the Android app's JS runtime\n3. `execute_js_dir.*` bundles a directory entry first, so local modules can be resolved in one pushed artifact\n4. Inline JSON parameters are first written to a temp JSON file, then pushed to the device as `params_file_path`\n5. An ADB broadcast is sent to the application with the execution request\n6. The application's BroadcastReceiver receives the request and uses `JsEngine` to execute the function or whole script\n7. Execution results are written to a dedicated JSON file on the device\n8. The executor waits for that file, prints it, and then cleans it up\n\n## Troubleshooting\n\n### Common Issues\n\n1. **ADB command not found** \n Ensure the Android SDK's platform-tools directory is in your PATH environment variable.\n\n2. **No devices detected**\n - Make sure the device is connected\n - Ensure USB debugging is enabled\n - Check that the computer is authorized for USB debugging\n\n3. **Broadcast sent but function not executed**\n - Check the logs for error messages\n - Confirm the application is running\n - Verify the receiver is correctly registered\n\n4. **JavaScript errors**\n - Check for TypeScript-specific syntax (like type annotations)\n - Ensure functions are properly exported\n - Verify parameter formats are correct\n \n## Required Permissions\n\nThis feature requires the following permissions:\n\n- Read and write external storage\n- Permission to receive broadcasts\n\n## Security Considerations\n\n- This feature should only be used for development and debugging purposes\n- In production environments, this feature should be disabled or restricted to prevent security risks \n","tools/compose_dsl/COMPOSE_DSL_DEBUG_README.md":"# Compose DSL UI Dump\n\n## 用途\n\n`dump_current_compose_dsl_ui.bat` 用来抓取当前正在显示的 `compose_dsl` 页面运行时快照，方便排查：\n\n- 脚本输出的组件树是否正确\n- 宿主解析后的树是否一致\n- 布局坐标和尺寸是否符合预期\n- 当前页面 `state` / `memo` 是否异常\n\n这套工具适合排查“结构看起来对，但界面显示不对”的问题。\n\n## 使用方法\n\n1. 用宿主打开你要调试的 `compose_dsl` 页面。\n2. 等页面进入你想观察的状态。\n3. 运行：\n\n```bat\nd:\\Code\\prog\\assistance\\tools\\compose_dsl\\dump_current_compose_dsl_ui.bat\n```\n\n## 前提条件\n\n- 已安装并可使用 `adb`\n- 至少连接了一台可调试设备\n- 设备上的宿主版本已经包含当前调试导出逻辑\n- 设备上已安装 `com.ai.assistance.operit.debug` 或 `com.ai.assistance.operit`；脚本未指定时优先使用 Debug 包\n\n如果连接了多台设备，脚本会提示选择目标设备。\n\n如果 Debug 和 Release APK 同时安装，可以用环境变量指定目标：\n\n```bat\nset OPERIT_APP_PACKAGE=com.ai.assistance.operit\nd:\\Code\\prog\\assistance\\tools\\compose_dsl\\dump_current_compose_dsl_ui.bat\n```\n\n## 导出位置\n\n脚本会把文件拉回本地目录：\n\n```text\nd:\\Code\\prog\\assistance\\debug_output\\compose_dsl_dump\\<时间戳>\\\n```\n\n例如：\n\n```text\nd:\\Code\\prog\\assistance\\debug_output\\compose_dsl_dump\\20260425-153457\\\n```\n\n## 文件说明\n\n- `dump_manifest.json`\n 当前页面的基础信息，包括包名、模块名、phase、是否仍在 loading / dispatching。\n\n- `source_script.js`\n 当前页面实际执行的 UI 脚本源码。\n\n- `raw_render_result.txt`\n JS 原始 render 返回值的文本形式。\n\n- `raw_render_result.json`\n 如果原始返回值可以解析为 JSON，这里会保存格式化后的版本。\n\n- `parsed_render_result.json`\n 宿主解析后的完整 render 结果。\n\n- `compose_tree.txt`\n 解析后的组件树，可快速看结构。\n\n- `compose_tree.json`\n 组件树的 JSON 形式。\n\n- `layout_nodes.txt`\n 每个节点的真实布局信息，包括 `x / y / width / height`。\n\n- `layout_nodes.json`\n 布局信息的 JSON 形式。\n\n- `compose_layout_tree.txt`\n “组件树 + 布局信息”合并后的可读版本。\n\n- `state.json`\n 当前页面状态。\n\n- `memo.json`\n 当前页面 memo。\n\n## 推荐排查顺序\n\n1. 先看 `dump_manifest.json`\n 确认抓到的是不是当前页面，以及页面是不是已经稳定。\n\n2. 再看 `compose_tree.txt`\n 判断脚本输出结构是否正确。\n\n3. 再看 `layout_nodes.txt` 或 `compose_layout_tree.txt`\n 判断真实布局是不是出了问题。\n\n4. 如果怀疑状态异常，再看 `state.json`\n 确认是不是脚本状态导致界面不对。\n\n5. 如果怀疑宿主解析有偏差，再对比：\n `raw_render_result.json` 和 `parsed_render_result.json`\n\n## 常见场景\n\n- 文本、图标、按钮没有居中\n- `weight`、`fillMaxWidth`、`padding` 没按预期生效\n- `onLoad` 后页面状态和预期不一致\n- 脚本写出来的树和宿主最终理解的树不同\n\n## 注意事项\n\n- 这套工具抓的是“当前正在显示的页面快照”，不是历史页面。\n- 如果页面还在频繁重组或异步加载，建议等稳定后再抓一次。\n- 如果宿主调试导出逻辑有更新，需要重新安装宿主后才能看到新导出字段。\n","tools/compose_dsl/README.md":"# compose_dsl artifact generator\n\nGenerates compose_dsl artifacts from Compose source jars in Gradle cache.\n\n- Kotlin renderer registry:\n - `app/src/main/java/com/ai/assistance/operit/ui/common/composedsl/ToolPkgComposeDslGeneratedRegistry.kt`\n- Kotlin renderers:\n - `app/src/main/java/com/ai/assistance/operit/ui/common/composedsl/ToolPkgComposeDslGeneratedRenderers.kt`\n- TypeScript generated bindings:\n - `examples/types/compose-dsl.material3.generated.d.ts`\n\nRun:\n\n```bash\npython tools/compose_dsl/generate_compose_dsl_artifacts.py\n```\n\nNotes:\n- Source jars are resolved from `~/.gradle/caches/modules-2/files-2.1`.\n- If jars are missing, sync/build once to download dependencies.\n- Generator behavior:\n - Keeps dedicated renderers for core complex nodes (TextField/Icon/Card/Surface, etc.).\n - Auto-discovers additional public `@Composable` functions from Material3/Foundation and\n generates generic renderers/registry/TS props when required params are mappable.\n - `ToolPkgComposeDslGeneratedRenderers.kt.tpl` is now a thin scaffold with helper functions;\n component renderers are injected at `// __GENERATED_COMPONENT_RENDERERS__`.\n","tools/adb/JS_ADB_README_zh.md":"# ADB JavaScript 执行与调试说明\n\n这套 ADB JS 脚本不是单纯的“把一个文件推到手机上跑一下”。\n在 Operit 仓库里，它们是主要的 **安卓端 JavaScript 运行、调试与验证入口**。\n\n它们适合用于：\n\n- 直接把 JS 推到真实 Android 设备上运行\n- 在不走完整导入流程时调试普通 `.js` sandbox / package\n- 验证导出函数的参数传递、返回值、`complete(...)`、结构化结果\n- 复现只能在设备侧出现的运行时问题\n- 运行 `app/src/androidTest/js` 下的 JS bridge / script mode / smoke test 资产\n\n如果你要直接执行“顶层脚本模式”，而不是调用导出函数，请使用 `run_sandbox_script.sh` / `run_sandbox_script.bat`。\n\n## 工具分工\n\n### `tools/adb/execute_js.bat` / `tools/adb/execute_js.sh`\n\n这是最常用的单文件运行器。\n\n作用：\n\n- 把一个 JS 文件临时推到设备\n- 在 Operit 的 Android JS runtime 里调用某个导出函数\n- 返回结构化结果\n\n适合：\n\n- 普通单文件 JS 调试\n- 快速验证某个函数逻辑\n- 复现设备侧 bug\n- 开发普通 `.js` package 时做单次验证\n\n### `tools/adb/execute_js_dir.bat` / `tools/adb/execute_js_dir.sh`\n\n这是目录入口运行器。\n\n作用：\n\n- 以目录为单位执行入口文件\n- 先做 bundle，再推送到设备\n- 支持本地 `require(...)` / 多文件依赖\n\n适合：\n\n- 入口依赖多个本地模块\n- 运行 `app/src/androidTest/js` 里的测试入口\n- 跑 browser / bridge / harness 一类目录化测试\n\n### `tools/adb/run_sandbox_script.bat` / `tools/adb/run_sandbox_script.sh`\n\n这是脚本模式运行器。\n\n作用：\n\n- 直接执行顶层 sandbox script\n- 不要求导出函数\n- 适合验证 script mode 合约\n\n适合：\n\n- 快速跑一段顶层脚本\n- 验证 `emit(...)` / `complete(...)` / `return`\n- 做 inline snippet / top-level 行为测试\n\n## 真实测试资产\n\n仓库里的 [app/src/androidTest/js](/d:/Code/prog/assistance/app/src/androidTest/js) 不是普通示例目录，而是这套工具的重要使用场景之一。\n\n其中包括：\n\n- JS bridge contract 测试\n- JS bridge edge case 测试\n- script mode contract 测试\n- browser tool smoke / probe\n- utility / ffmpeg / ttscleaner 等运行时测试资产\n\n典型目录：\n\n- [bridge_contract](/d:/Code/prog/assistance/app/src/androidTest/js/com/ai/assistance/operit/core/tools/javascript/bridge_contract)\n- [bridge_edges](/d:/Code/prog/assistance/app/src/androidTest/js/com/ai/assistance/operit/core/tools/javascript/bridge_edges)\n- [script_mode_contract](/d:/Code/prog/assistance/app/src/androidTest/js/com/ai/assistance/operit/core/tools/javascript/script_mode_contract)\n- [browser main.js](/d:/Code/prog/assistance/app/src/androidTest/js/com/ai/assistance/operit/core/tools/defaultTool/standard/browser/main.js)\n- [ttscleaner.js](/d:/Code/prog/assistance/app/src/androidTest/js/com/ai/assistance/operit/util/ttscleaner/ttscleaner.js)\n\n## 先记结论\n\n如果你只是想快速判断“我现在该用哪个”：\n\n- 调一个普通 `.js` 文件里导出的函数，用 `execute_js.*`\n- 入口文件依赖同目录其他模块，或者你在跑 `app/src/androidTest/js` 里的目录化测试，用 `execute_js_dir.*`\n- 想验证顶层 script mode 行为，不想写导出函数，用 `run_sandbox_script.*`\n- 你改的是 `examples/` 里的 package / toolpkg，想热更新到设备里的包系统，再去 UI 或包管理里验证，用 `tools/example_packages/sync_example_packages.py`\n- 你改的是 `examples/` 里的 toolpkg 调试工具，例如 `operit_editor` 的 `debug_install_toolpkg`，通常是先 `tools/example_packages/sync_example_packages.py`，再用 `execute_js.bat` 去调这个工具\n\n## 快速开始\n\n### Windows：执行单文件导出函数\n\n```cmd\ntools\\adb\\execute_js.bat path\\to\\your\\script.js functionName @params.json\n```\n\n示例：\n\n```cmd\ntools\\adb\\execute_js.bat examples\\operit_editor.js debug_install_toolpkg @params.json\n```\n\n### Linux/macOS：执行单文件导出函数\n\n```bash\n./tools/adb/execute_js.sh path/to/your/script.js functionName '{\"param1\":\"value1\"}'\n```\n\n### 执行整个目录入口（支持 `require(...)`）\n\nWindows：\n\n```cmd\ntools\\adb\\execute_js_dir.bat app\\src\\androidTest\\js com\\ai\\assistance\\operit\\core\\tools\\javascript\\bridge_contract\\bridge_contract_runner.js run @params.json\ntools\\adb\\execute_js_dir.bat app\\src\\androidTest\\js com\\ai\\assistance\\operit\\core\\tools\\defaultTool\\standard\\browser\\main.js run \"{}\"\n```\n\nLinux/macOS：\n\n```bash\n./tools/adb/execute_js_dir.sh app/src/androidTest/js com/ai/assistance/operit/core/tools/javascript/bridge_contract/bridge_contract_runner.js run @params.json\n```\n\n### 执行顶层 sandbox script\n\nWindows：\n\n```cmd\ntools\\adb\\run_sandbox_script.bat temp\\probe.js @params.json\n```\n\nLinux/macOS：\n\n```bash\n./tools/adb/run_sandbox_script.sh temp/probe.js @params.json\n```\n\n## 结果查看\n\n这些执行器现在不是靠 `adb logcat` 抓输出，而是等待设备上的结构化结果文件。\n执行结束后会打印 JSON 结果，通常包含：\n\n- `success`\n- `result`\n- `error`\n- `events`\n- `durationMs`\n\n这对于运行时调试和 JS 合约测试特别有用，因为失败原因会更集中，不需要再手翻大量日志。\n\n可以通过下面的环境变量调整等待超时：\n\n```cmd\nset OPERIT_RESULT_WAIT_SECONDS=30\ntools\\adb\\execute_js.bat examples\\my_script.js main @params.json\n```\n\n### Debug / Release 双包选择\n\n这四个 ADB 执行脚本会同时支持以下两个 Operit applicationId：\n\n- `com.ai.assistance.operit.debug`\n- `com.ai.assistance.operit`\n\n未设置配置时，脚本会查询设备上的已安装包并优先选择 Debug 包；只安装 Release 包时会使用 Release 包。每次执行都会打印最终选择的 applicationId，文件目录和 receiver 都会跟随该值变化。JS 执行 action 固定为 `com.ai.assistance.operit.EXECUTE_JS`，因为它是 Receiver 的跨构建协议，不随 applicationId 追加 `.debug`。\n\n如果两种 APK 同时安装，可以显式指定：\n\n```cmd\nset OPERIT_APP_PACKAGE=com.ai.assistance.operit.debug\ntools\\adb\\execute_js.bat examples\\my_script.js main @params.json\n```\n\nLinux/macOS：\n\n```bash\nOPERIT_APP_PACKAGE=com.ai.assistance.operit.debug ./tools/adb/execute_js.sh examples/my_script.js main '{}'\n```\n\nToolPkg 调试安装器支持同样的环境变量，也支持 `--app-package `；示例包热更新脚本支持同名参数。指定的包必须已经安装在所选设备上。\n\n## 作用和调用方法\n\n### 1. `execute_js.*` 是干什么的\n\n它是最直接的“安卓真机 JS 运行器”。\n\n你给它：\n\n- 一个 JS 文件\n- 一个导出函数名\n- 一份 JSON 参数\n\n它就会把这个文件放到设备上，在 Operit 的 JS runtime 里直接调用这个函数。\n\n适合：\n\n- 单文件功能验证\n- 调某个导出函数\n- 复现设备侧运行时报错\n- 调试 package 里的某个工具实现\n\n最常见调用：\n\n```cmd\ntools\\adb\\execute_js.bat examples\\operit_editor.js debug_install_toolpkg @params.json\n```\n\n你在写新脚本时，最小可运行要求就是：\n\n- 文件是合法 JS，不是 TS 原文\n- 目标函数已经导出\n- 参数按 JSON 传入\n\n例如：\n\n```javascript\nfunction main(params) {\n return {\n success: true,\n echo: params\n };\n}\n\nexports.main = main;\n```\n\n### 2. `execute_js_dir.*` 是干什么的\n\n它是“目录入口执行器”。\n\n如果你的入口文件不是一个孤立文件，而是还会 `require(\"./xxx\")`、依赖同目录工具模块、测试工具、runner、helper，那么不要继续用单文件执行器，直接换这个。\n\n适合：\n\n- `app/src/androidTest/js` 下的测试入口\n- bridge contract / browser smoke / harness 这种目录化测试\n- 你自己新加了一套多文件测试目录\n\n最常见调用：\n\n```cmd\ntools\\adb\\execute_js_dir.bat app\\src\\androidTest\\js com\\ai\\assistance\\operit\\core\\tools\\javascript\\bridge_contract\\bridge_contract_runner.js run @params.json\n```\n\n调用格式：\n\n```cmd\ntools\\adb\\execute_js_dir.bat <根目录> <入口相对路径> <函数名> [JSON参数|@参数文件]\n```\n\n这里最关键的是：\n\n- 第一个参数是“测试根目录”\n- 第二个参数是“相对这个根目录的入口文件”\n- 第三个参数通常是 runner 暴露的 `run`\n\n### 3. `run_sandbox_script.*` 是干什么的\n\n它不是调导出函数，而是直接跑“整段顶层脚本”。\n\n适合：\n\n- 验证 script mode 合约\n- 快速试 `emit(...)`\n- 快速试 `complete(...)`\n- 快速做一段临时探针脚本\n\n最常见调用：\n\n```cmd\ntools\\adb\\run_sandbox_script.bat temp\\probe.js @params.json\n```\n\n如果你的代码天然就是“顶层执行”，这个比先包一层 `exports.main = ...` 更顺手。\n\n### 4. `tools/example_packages/sync_example_packages.py` 是干什么的\n\n它不是单纯的“复制文件脚本”，而是 `examples/` 包开发时的同步入口。\n\n它最重要的作用是：\n\n- 先把 `examples/` 里相关 TS 预编译成 JS\n- 把带 `manifest.json` / `manifest.hjson` 的目录打成 `.toolpkg`\n- 把普通 `.js` 或 `.toolpkg` 同步到 `app/src/main/assets/packages`\n- 如果连着设备，还会把变化的包热更新到设备\n\n所以它适合：\n\n- 你改的是 `examples/` 里的正式包\n- 你想让包管理 / 沙箱包列表 / 内置加载逻辑看到最新结果\n- 你要验证 folder -> `.toolpkg` -> debug install 这条链路\n\n最常见调用：\n\n```cmd\nd:\\Code\\prog\\assistance\\.venv\\Scripts\\python.exe d:\\Code\\prog\\assistance\\tools\\example_packages\\sync_example_packages.py --include sidebar_bing_action\n```\n\n如果你要全量测试 examples 里的可同步项目，可以用：\n\n```cmd\nd:\\Code\\prog\\assistance\\.venv\\Scripts\\python.exe d:\\Code\\prog\\assistance\\tools\\example_packages\\sync_example_packages.py --mode test\n```\n\n如果你只想更新本地资产，不想碰设备热更新：\n\n```cmd\nd:\\Code\\prog\\assistance\\.venv\\Scripts\\python.exe d:\\Code\\prog\\assistance\\tools\\example_packages\\sync_example_packages.py --include sidebar_bing_action --no-hot-reload\n```\n\n## 测试如何加\n\n这里最容易混淆的是：并不是所有“测试”都要放到同一个地方。\n\n### 1. 加单文件函数测试\n\n如果你只是想验证一个函数逻辑是否正确，最轻量的方式是：\n\n- 先写一个普通 JS 文件\n- 导出一个 `main` 或 `run`\n- 用 `execute_js.*` 直接调\n\n这种方式适合：\n\n- 小逻辑验证\n- 参数解析验证\n- 返回结构验证\n- 某个 bug 的最小复现\n\n### 2. 加目录化运行时测试\n\n如果你的测试会引用多个本地模块，建议直接放到 [app/src/androidTest/js](/d:/Code/prog/assistance/app/src/androidTest/js) 下面，按一个小目录来组织。\n\n推荐组织方式：\n\n- 一个入口 runner 文件，例如 `xxx_runner.js`\n- 若干测试文件 / helper 文件\n- runner 暴露 `run(params)`\n\n这样你就能直接用：\n\n```cmd\ntools\\adb\\execute_js_dir.bat app\\src\\androidTest\\js <你的入口相对路径> run \"{}\"\n```\n\n这类测试最适合：\n\n- bridge contract\n- 多模块协作\n- 真实运行时 smoke test\n- 需要本地 `require(...)` 的测试\n\n### 3. 加 script mode 测试\n\n如果你要测的是：\n\n- 顶层 `return`\n- `emit(...)`\n- `complete(...)`\n- script mode 和 function mode 的差异\n\n那就不要强行塞进导出函数测试，直接写成 script mode 文件，再用 `run_sandbox_script.*` 跑。\n\n### 4. 给 `examples/` 里的 package / toolpkg 加验证\n\n如果你加的是一个真正要被包系统加载的例子，重点不只是“JS 能跑”，还要验证“包能不能被同步、刷新、安装、识别”。\n\n这时推荐这样加：\n\n- 在 `examples/` 下新增或修改你的 `.ts` / `.js` / manifest 目录\n- 如果是目录化 package，保证它有 `manifest.json` 或 `manifest.hjson`\n- 用 `tools/example_packages/sync_example_packages.py` 同步\n- 再用 `execute_js.bat` 去调用相关调试工具，或者直接在应用里验证加载结果\n\n也就是说：\n\n- 运行器测试的是“这段 JS 在安卓 runtime 里能不能执行”\n- `tools/example_packages/sync_example_packages.py` 测的是“这个 examples 包能不能进入真正的包加载链路”\n\n## 和 `tools/example_packages/sync_example_packages.py` 怎么配合\n\n### 场景 1：你改的是普通 JS 脚本\n\n这种情况下通常不需要先 sync。\n\n直接：\n\n```cmd\ntools\\adb\\execute_js.bat path\\to\\script.js main @params.json\n```\n\n因为你只是在验证脚本逻辑，不是在验证包加载。\n\n### 场景 2：你改的是 `examples/` 里的 package\n\n推荐顺序：\n\n1. 改 `examples/...`\n2. 运行 `tools/example_packages/sync_example_packages.py`\n3. 看它是否把输出同步到 `app/src/main/assets/packages`\n4. 如果连着设备，顺便验证热更新是否成功\n5. 再在应用里或用调试工具验证功能\n\n这种适合：\n\n- 普通 `.js` 包\n- 要进入 packages 列表的例子\n- 改包描述、manifest、依赖结构\n\n### 场景 3：你改的是目录型 toolpkg\n\n这是最需要和 `tools/example_packages/sync_example_packages.py` 配合的场景。\n\n推荐顺序：\n\n1. 改 `examples/`\n2. 运行 `tools/example_packages/sync_example_packages.py --include <目录名>`\n3. 让它把目录打成 `.toolpkg`\n4. 让它把生成物同步到 assets 和设备\n5. 再用 `operit_editor` 的 `debug_install_toolpkg` 或相关调试入口验证安装结果\n\n这样测到的是完整链路：\n\n- 目录内容是否能正确打包\n- `.toolpkg` 是否能被热更新到设备\n- debug install 是否能识别这个包\n- 包刷新后是否真的进入加载列表\n\n### 场景 4：你改的是 `operit_editor` 这类调试工具本身\n\n推荐顺序：\n\n1. 先 `tools/example_packages/sync_example_packages.py` 更新 `operit_editor` 自己\n2. 再准备一个待安装的 package / toolpkg\n3. 用 `execute_js.bat` 调 `operit_editor.js` 的调试函数\n4. 看结构化结果里的成功、失败和相关告警\n\n例如：\n\n```cmd\nd:\\Code\\prog\\assistance\\.venv\\Scripts\\python.exe d:\\Code\\prog\\assistance\\tools\\example_packages\\sync_example_packages.py --include operit_editor --include sidebar_bing_action\ntools\\adb\\execute_js.bat examples\\operit_editor.js debug_install_toolpkg @params.json\n```\n\n这适合验证：\n\n- debug install 调用方式对不对\n- folder 打包成 `.toolpkg` 后能否被正确安装\n- 安装结束后返回给调用方的告警 / 错误是否完整\n\n## 推荐调用清单\n\n### 1. 跑一个普通导出函数\n\n```cmd\ntools\\adb\\execute_js.bat examples\\my_script.js main @params.json\n```\n\n### 2. 跑一个 `androidTest/js` 目录测试入口\n\n```cmd\ntools\\adb\\execute_js_dir.bat app\\src\\androidTest\\js com\\ai\\assistance\\operit\\core\\tools\\javascript\\bridge_contract\\bridge_contract_runner.js run @params.json\n```\n\n### 3. 跑一个顶层 script mode 探针\n\n```cmd\ntools\\adb\\run_sandbox_script.bat temp\\probe.js @params.json\n```\n\n### 4. 同步一个 `examples/` 包到 assets 和设备\n\n```cmd\nd:\\Code\\prog\\assistance\\.venv\\Scripts\\python.exe d:\\Code\\prog\\assistance\\tools\\example_packages\\sync_example_packages.py --include sidebar_bing_action\n```\n\n### 5. 同步后再调用调试安装工具\n\n```cmd\nd:\\Code\\prog\\assistance\\.venv\\Scripts\\python.exe d:\\Code\\prog\\assistance\\tools\\example_packages\\sync_example_packages.py --include operit_editor --include sidebar_bing_action\ntools\\adb\\execute_js.bat examples\\operit_editor.js debug_install_toolpkg @params.json\n```\n\n## Script Mode 注意事项\n\n当你使用 `run_sandbox_script.sh` / `run_sandbox_script.bat`，或者在包工具里走 `debug_run_sandbox_script` 的 `source_code` 路径时，代码会按 **顶层脚本** 执行，而不是按 `function(params) { ... }` 执行。\n\n这意味着：\n\n- 用 `console.log(...)` / `console.info(...)` / `console.warn(...)` / `console.error(...)` 打日志\n- 用 `emit(...)` 发送中间事件\n- 用 `return result` 或 `complete(...)` 完成执行\n- 不要假设 `params` 会直接出现在顶层作用域\n- 不要用 `intermediate(...)`，当前约定是 `emit(...)`\n\n推荐顶层片段：\n\n```javascript\nconsole.log(\"inline debug start\");\nemit({ stage: \"inline\", ok: true });\ncomplete({\n success: true,\n message: \"inline debug finished\"\n});\n```\n\n## JS 文件要求\n\n### 对 `execute_js.*`\n\n- 文件必须是合法 JavaScript\n- 目标函数必须导出，例如 `exports.myFunction = myFunction`\n- 函数接收 `params`\n- 可以 `return result`，也可以调用 `complete(result)`\n\n示例：\n\n```javascript\nfunction myFunction(params) {\n const name = params.name || \"default\";\n return {\n success: true,\n result: `Result: ${name}`\n };\n}\n\nexports.myFunction = myFunction;\n```\n\n### 对 `run_sandbox_script.*`\n\n- 不要求导出函数\n- 按顶层脚本模式运行\n- 更适合 script mode 验证与快速 probe\n\n## 技术路径\n\n1. 脚本把 JS 文件推到设备临时目录\n2. `execute_js_dir.*` 会先把目录入口 bundle 成单文件\n3. JSON 参数会先落成临时文件，再推到设备，避免命令行引号问题\n4. 通过 ADB broadcast 发送执行请求\n5. 应用内的 `ScriptExecutionReceiver` 接收请求\n6. `JsEngine` 在应用运行时里执行函数或脚本\n7. 执行结果写入设备侧 JSON 文件\n8. 执行器等待这个结果文件并输出\n\n相关接收器：\n\n- [ScriptExecutionReceiver.kt](/d:/Code/prog/assistance/app/src/main/java/com/ai/assistance/operit/core/tools/javascript/ScriptExecutionReceiver.kt)\n- [ToolPkgDebugInstallReceiver.kt](/d:/Code/prog/assistance/app/src/main/java/com/ai/assistance/operit/core/tools/packTool/ToolPkgDebugInstallReceiver.kt)\n\n## 故障排查\n\n### 1. 找不到 ADB\n\n确认 Android SDK 的 `platform-tools` 已加入 PATH。\n\n### 2. 没有检测到设备\n\n- 确认设备已连接\n- 确认已开启 USB 调试\n- 确认电脑已获得调试授权\n\n### 3. 广播发出去了但没有执行\n\n- 确认应用已安装\n- 确认目标 Receiver 已注册\n- 看结构化结果里的 `error` / `events`\n\n### 4. JS 语法错误\n\n- 不要把 TypeScript 语法直接喂给运行器\n- 检查导出函数是否存在\n- 检查参数 JSON 是否正确\n\n### 5. 多文件依赖跑不起来\n\n优先改用 `execute_js_dir.*`，不要继续用单文件执行器硬跑 `require(...)` 场景。\n\n## 安全说明\n\n- 这套工具主要用于开发、调试、验证\n- 它们依赖应用内 Receiver 接收外部 broadcast\n- 在生产环境中应谨慎暴露这类调试入口\n","tools/mcp_bridge/tsconfig.json":"{\n \"compilerOptions\": {\n \"target\": \"es2020\",\n \"module\": \"NodeNext\",\n \"outDir\": \"./dist\",\n \"rootDir\": \".\",\n \"strict\": true,\n \"esModuleInterop\": true,\n \"skipLibCheck\": true,\n \"forceConsistentCasingInFileNames\": true,\n \"resolveJsonModule\": true,\n \"moduleResolution\": \"NodeNext\",\n \"sourceMap\": true,\n \"declaration\": true,\n \"downlevelIteration\": true\n },\n \"include\": [\n \"*.ts\"\n ],\n \"exclude\": [\n \"node_modules\",\n \"dist\"\n ]\n}","tools/mcp_bridge/README.md":"# MCP TCP 桥接器\n\n这个工具只负责基于 STDIO 的本地 MCP 服务器与 TCP 客户端之间的桥接，让无法直接访问命名管道(FIFO)的客户端，例如 Android 应用，能够与本地进程通信。\n\n远程 HTTP Stream 和 SSE MCP 服务由 Android 端的 Kotlin MCP SDK 直接连接，不经过 bridge。\n\n## 功能特点\n\n- 将STDIO型MCP服务器桥接到TCP端口\n- 支持并发连接\n- 自动重启崩溃的MCP进程\n- 优雅地处理连接错误和进程终止\n- 详细的日志记录\n\n## 安装\n\n```bash\n# 在项目根目录安装工作区依赖\npnpm install\n\n# 编译 bridge 并同步 Android assets\npnpm --dir tools/mcp_bridge run build\n```\n\n`tools/mcp_bridge` 的依赖由根目录 `pnpm-lock.yaml` 统一锁定。构建会更新\n`app/src/main/assets/bridge/index.js` 和 `app/src/main/assets/bridge/spawn-helper.js`。\n\n## 使用方法\n\n### 基本用法\n\n```bash\n# 使用默认配置启动\npnpm --dir tools/mcp_bridge start\n```\n\n这将在默认端口8752上启动桥接器，连接到`../your-mcp-server.js`。\n\n### 高级用法\n\n您可以通过命令行参数自定义桥接器：\n\n```bash\n# 格式\npnpm --dir tools/mcp_bridge start -- [端口] [命令] [参数...]\n\n# 示例：在端口9000上启动，连接到Python MCP服务器\npnpm --dir tools/mcp_bridge start -- 9000 python ../python_mcp_server.py\n\n# 示例：连接到Java MCP服务器\npnpm --dir tools/mcp_bridge start -- 8752 java -jar ../java_mcp_server.jar\n```\n\n### 在代码中使用\n\n您也可以在其他Node.js应用中使用这个桥接器：\n\n```typescript\nimport McpBridge from './path/to/bridge';\n\nconst bridge = new McpBridge({\n port: 8752,\n host: '127.0.0.1',\n mcpCommand: 'node',\n mcpArgs: ['../your-mcp-server.js'],\n verbose: true\n});\n\nbridge.start();\n```\n\n## 在Termux中使用\n\n在Termux环境中，可以按以下步骤设置：\n\n```bash\n# 安装Node.js\npkg install nodejs\n\n# 克隆或下载此项目\ngit clone <项目URL>\ncd <项目目录>\n\n# 安装根工作区依赖\npnpm install\n\n# 编译并同步 Android assets\npnpm --dir tools/mcp_bridge run build\n\n# 启动桥接器\npnpm --dir tools/mcp_bridge start -- 8752 node ../your-mcp-server.js\n```\n\n## Android客户端示例\n\n以下是Android客户端连接到MCP桥接器的示例代码：\n\n```kotlin\nimport kotlinx.coroutines.Dispatchers\nimport kotlinx.coroutines.withContext\nimport java.io.BufferedReader\nimport java.io.InputStreamReader\nimport java.io.PrintWriter\nimport java.net.Socket\nimport org.json.JSONObject\n\nclass McpClient {\n private val host = \"127.0.0.1\"\n private val port = 8752\n \n suspend fun sendRequest(method: String, params: JSONObject): JSONObject = withContext(Dispatchers.IO) {\n Socket(host, port).use { socket ->\n val input = BufferedReader(InputStreamReader(socket.getInputStream()))\n val output = PrintWriter(socket.getOutputStream(), true)\n \n // 创建JSONRPC请求\n val requestId = System.currentTimeMillis().toString()\n val request = JSONObject().apply {\n put(\"jsonrpc\", \"2.0\")\n put(\"id\", requestId)\n put(\"method\", method)\n put(\"params\", params)\n }\n \n // 发送请求\n output.println(request.toString())\n \n // 读取响应\n val response = input.readLine()\n JSONObject(response)\n }\n }\n}\n```\n\n## 注意事项\n\n- 确保MCP服务器程序已正确安装并可执行\n- 桥接器应当与内部网络一起使用，不要暴露到公共互联网\n- 对于生产环境，考虑添加认证和加密层\n- 在Android环境中，确保应用有INTERNET权限\n","tools/github/issues_open_ai.md":"# Issue Triage Report\n\n## Overall summary (counts by category, quick highlights)\n**总计议题数：** 45 个 (状态：open)\n\n**按类别统计：**\n* **Bug (缺陷):** 7 个 (含 3 个 P0)\n* **无障碍/权限:** 6 个 (含 2 个 P1)\n* **用户界面 (UI):** 11 个 (含 2 个 P1)\n* **工具/功能管理:** 9 个 (均为 P1/P2)\n* **工具/自动化:** 6 个 (含 2 个 P1)\n* **模型/API 集成:** 3 个 (含 1 个 P1)\n* **国际化 (i18n):** 1 个 (P1)\n* **配置/同步:** 1 个 (P1)\n* **模型 / AI 核心:** 2 个 (含 1 个 P1)\n* **数据导入/导出:** 1 个 (P2)\n* **应用分发:** 1 个 (P2)\n* **终端:** 1 个 (P1，与 UI 类别 #237 重叠)\n\n**快速亮点：**\n* **高优先级缺陷 (P0):** 存在 3 个关键 Bug，均导致核心的 UI 信息获取/自动化功能在特定系统上完全失效 (#125, #101, #67)。\n* **权限与兼容性问题突出：** 多个 P1 议题涉及 Android 系统（特别是 ColorOS、MIUI、鸿蒙）的权限授予失败、服务连接异常或文件访问问题 (#306, #283, #317)。\n* **功能建议集中：** 大量 P1/P2 议题围绕 **UI/UX 优化**、**自动化功能增强**、**AI 执行效率提升**（如安静模式、变量存储）和**配置管理**（如对话绑定模型、配置同步）提出建议。\n* **模型集成问题：** 存在通过 oneAPI 调用智谱模型失败 (#277) 和本地 llama.cpp 连接问题 (#258)，影响模型可用性。\n\n## Top priorities (P0 then P1)\n\n**P0 (关键缺陷，需立即调查):**\n1. **#125**: UI信息始终是Operit AI应用的 - AI 操作其他应用时获取自身 UI 信息，导致核心自动化功能失效。\n2. **#101**: [bug] UI调试工具无法获取当前屏幕内容 - 在 ColorOS 上触发系统返回，无法获取屏幕内容。\n3. **#67**: Miui 14.0.4 在debugger和root模式下均无法获取页面元素 - 在 MIUI 上 UI 数据获取完全失败。\n\n**P1 (高优先级功能/缺陷):**\n1. **#306**: [BUG]由于无障碍辅助app未申请任何权限，导致ColorOS无法解除权限限制 - 权限流程阻塞，影响核心功能启用。\n2. **#312**: English selected but large parts of UI still in Chinese - 国际化不完整，影响非中文用户体验。\n3. **#266**: 角色切换后主界面历史对话不显示，仅在悬浮窗显示 - 数据展示不一致，影响使用连贯性。\n4. **#283**: Bug: 无障碍服务已开启但AI助手接口服务显示未连接 - 服务状态指示错误，误导用户。\n5. **#317**: [bug]在Android8中，应用无法读取，修改Android设备本机中的文件 - 基础文件功能在特定系统失效。\n6. **#277**: 使用oneapi集成智谱code模型调用失败 - 第三方模型集成失败，影响功能可用性。\n7. **#321**: 添加配置同步功能 - 重要的用户体验增强功能，设计复杂度高。\n8. **#237**: 建议 (综合性UI/功能建议，含终端SSH想法)\n9. **#10**: 十条建议 (基础功能与UI改进建议集合)\n10. **#248**: 小功能拓展建议 (自动截图、连续对话、定时提醒等)\n11. **#35**: 请增加识图找图功能... (补充UI自动化能力)\n12. **#216**: Local llm implementation cpu/gpu/npu (支持本地LLM)\n13. **#165**: code_runner中的代码显示bug (显示格式错误)\n\n## By category (each category heading, list issues)\n\n### Bug (缺陷)\n* **#125 (P0)**: ui信息始终是Operit AI应用的 - AI操作其他应用时，获取的UI信息错误（始终是本应用），导致功能失效。 **行动：调查**\n* **#101 (P0)**: [bug] UI调试工具无法获取当前屏幕内容 - 在特定系统（Android 10 ColorOS）上，调用UI调试工具会触发系统返回，无法获取内容。 **行动：调查**\n* **#67 (P0)**: Miui 14.0.4 在debugger和root模式下均无法获取页面元素 - 在MIUI系统上，UI数据获取完全失败。 **行动：调查**\n* **#165 (P1)**: code_runner中的代码显示bug - code_runner显示代码时包含了前后标签，而非纯净代码。 **行动：修复**\n* **#27 (P2)**: 屏幕识别在某个软件里识别不出来东西 - 屏幕识别功能在特定软件中失效。 **行动：调查**\n* **#291 (P2)**: 导入聊天记录报错 - 导入聊天记录时失败，报错“未找到有效聊天记录”或“格式转换失败”。 **行动：调查**\n* **#263 (P2)**: 搜索引擎使用结果提取的问题 - 使用百度搜索后，提取搜索结果详情页内容时经常遇到 404 错误。 **行动：调查**\n\n### 无障碍/权限\n* **#306 (P1)**: [BUG]由于无障碍辅助app未申请任何权限，导致ColorOS无法解除权限限制 - 在 ColorOS 上，由于应用未申请常规权限，导致无法在设置中解除权限限制，进而无法授予无障碍权限。 **行动：修复**\n* **#283 (P1)**: Bug: 无障碍服务已开启但AI助手接口服务显示未连接 - 无障碍服务已开启，但应用内显示 AI 助手接口服务未连接。 **行动：调查**\n* **#317 (P1)**: [bug]在Android8中，应用无法读取，修改Android设备本机中的文件 - 在 Android 8 (鸿蒙2) 设备上，应用无法读写设备本地文件（尽管 `code_runner` 和 `shell` 可用）。 **行动：调查**\n* **#316 (P2)**: 关于APP被关联启动 - 应用在关闭状态下被关联启动并弹出无法滑掉的通知，影响用户体验，寻求关闭方法。 **行动：调查**\n* **#307 (P2)**: 语音助手功能可用性低 - 语音助手存在多个问题：手势启动后不能直接语音输入、识别失败率高、建议调用系统接口、界面图标辨识度低。 **行动：调查**\n* **#250 (部分内容) (P2)**: 自动化任务遇到双开软件提示或系统权限弹窗时无法识别并选择。 **行动：设计**\n\n### 用户界面 (UI)\n* **#266 (P1)**: 角色切换后主界面历史对话不显示，仅在悬浮窗显示 - 切换角色卡后，主界面无法加载对应历史对话，仅悬浮窗部分显示，数据不同步。 **行动：修复**\n* **#320 (P1)**: 1、你一个对话问问题... - 包含多个 UI 交互问题：多对话卡顿、waifu模式表格显示异常、窗口模式切换冲突、颜色选择器可视化不足。 **行动：调查**\n* **#237 (P1)**: 建议 - 包含多项UI改进建议，如对话框背景、权限管理等。**设计**\n* **#10 (P1)**: 十条建议 - 包含多项基础功能与UI改进建议，如输入交互、导航、主题等。**设计**\n* **#268 (P2)**: 全屏\n","tools/mcp_bridge/package.json":"{\n \"name\": \"mcp-tcp-bridge\",\n \"version\": \"1.0.0\",\n \"description\": \"将STDIO型MCP服务器桥接到TCP端口\",\n \"main\": \"dist/index.js\",\n \"scripts\": {\n \"build\": \"tsc && pnpm run bundle && pnpm run copy\",\n \"bundle\": \"ncc build dist/index.js -o bundle && ncc build dist/spawn-helper.js -o bundle-helper\",\n \"copy\": \"node -e \\\"require('fs').copyFileSync('bundle/index.js', '../../app/src/main/assets/bridge/index.js')\\\" && node -e \\\"require('fs').copyFileSync('bundle-helper/index.js', '../../app/src/main/assets/bridge/spawn-helper.js')\\\"\",\n \"start\": \"node dist/index.js\",\n \"dev\": \"ts-node index.ts\",\n \"test\": \"echo \\\"Error: no test specified\\\" && exit 1\"\n },\n \"keywords\": [\n \"mcp\",\n \"bridge\",\n \"tcp\",\n \"stdio\"\n ],\n \"author\": \"\",\n \"license\": \"MIT\",\n \"dependencies\": {\n \"@modelcontextprotocol/sdk\": \"1.30.0\"\n },\n \"devDependencies\": {\n \"@types/node\": \"^18.0.0\",\n \"@vercel/ncc\": \"^0.38.1\",\n \"ts-node\": \"^10.9.1\",\n \"typescript\": \"^5.0.0\"\n }\n}\n"},"files":{"AGENTS.md":"# AGENTS.md\n\n执行准则章节是对Agent, AI 或 你 的限制，不是对项目或者软件的限制，无需写入文档\n## 执行准则\n- 默认不要执行编译、构建或测试命令。\n- 只有在用户明确要求时，才执行编译/构建/测试（例如 `./gradlew :app:compileDebugKotlin`、`npm run build`、`pnpm run build`）。\n- 创建分支时，必须遵守 `docs/doc-src/dev-core/CONTRIBUTING.md` 中“创建 Pull Request”的分支命名规范。\n\n当针对用户接口的方案更换时，一定要询问用户是否该版本为已发布版本。如果是，请做向前兼容。如果不是，请彻彻底底把老的方案的一切代码全部清理，除非是还能用到的一些部分就继续留着。\nDon't Break Userspace ，但是开发中能内部消解的方案更换不算，只要用户能尽可能拿到一样的接口就行\n但是需要给协作者必要的便利，提供恰当的文档说明和ci脚本\n\n如果是方案迭代，则只要在原来的基础上进行正常增删即可。\n\n除非用户要求，禁止写一切的回退代码。优先查找真正的发生原因。这是一条严格执行的规则，回退是正常被禁止的。\n\n严令禁止各种回退逻辑，包括“xxx才会退回”、“降级处理”、“优先 再”、“如果没有 就””要加fallback“这种字眼，绝对禁止！！！绝对禁止！！！这种就是兜底！出现一次严肃惩罚！\n\n禁止写任何的兜底代码，除非用户要求。\n\n用户开始骂的时候，需要道歉以及反思，安抚用户。\n\n用户表达愤怒的时候，需要先停下一切工作，仔细确认用户需求再去实现\n\n如果运行python，项目用的是venv（将迁移到pixi）\n\n严禁使用powershell编辑代码文件，否则会出现严重的编码错误和损坏。\n\n禁用Search files工具，请使用rg\n\n编写Typescript时，对于hook确定的类型，严禁回退兜底成任何unknown/any/带空类型/联合类型。更禁止使用String(??)形式兜底，返回什么就是什么。\n\n如果类型就是string|undef，那么不要直接as string！！那么请使用?? \"\"或者写个if！！\n\nts的报错catch后需要log出来\n\n代码的更改应维护相称的文档，注意docs\\doc-src\\before_docing.md\ndebug的时候注释记录你的修改意图（为什么，不这么做后果是什么）\n完成初步计划后，使用docs\\TODO\\README.md来细化计划\n","tools/github/issues_open.md":"# GitHub Issues (AAswordman/Operit)\n\nState: `open`\nCount: `42`\n\n- #321 [添加配置同步功能](https://github.com/AAswordman/Operit/issues/321) (open)\n - comments: 1 | updated: 2026-01-11T07:26:48Z\n- #312 [English selected but large parts of UI still in Chinese (agents/artifacts/settings)](https://github.com/AAswordman/Operit/issues/312) (open)\n - comments: 3 | updated: 2026-01-10T11:28:06Z\n- #320 [1、你一个对话问问题，新打开一个对话再问一个，两个对话都会卡住。 2、waifu模式就不会发完整表格了，会把表格拆分成一行一行 3、小窗模式跟系统小窗跟最大模式有时候会冲突，在小窗模式显示回复，放大以后就不显示了，过一会突然卡出来。 4、各个地方的颜色选择变化时来点可视化就舒服了 5、调用shizuku时就巨慢，一点小小的任务要好久](https://github.com/AAswordman/Operit/issues/320) (open)\n - comments: 0 | updated: 2026-01-09T08:31:56Z\n- #319 [折叠对话](https://github.com/AAswordman/Operit/issues/319) (open)\n - comments: 0 | updated: 2026-01-07T18:13:40Z\n- #318 [一些功能性建议](https://github.com/AAswordman/Operit/issues/318) (open)\n - comments: 0 | updated: 2026-01-07T17:57:06Z\n- #317 [[bug]在Android8中，应用无法读取，修改Android设备本机中的文件](https://github.com/AAswordman/Operit/issues/317) (open)\n - comments: 0 | updated: 2026-01-06T14:21:18Z\n- #316 [关于APP被关联启动](https://github.com/AAswordman/Operit/issues/316) (open)\n - comments: 0 | updated: 2026-01-05T10:32:40Z\n- #311 [一些建议](https://github.com/AAswordman/Operit/issues/311) (open)\n - comments: 0 | updated: 2026-01-03T03:47:49Z\n- #277 [使用oneapi集成智谱code模型调用失败](https://github.com/AAswordman/Operit/issues/277) (open)\n - comments: 5 | updated: 2026-01-01T07:46:15Z\n- #307 [语音助手功能可用性低](https://github.com/AAswordman/Operit/issues/307) (open)\n - comments: 2 | updated: 2025-12-31T14:58:03Z\n- #306 [[BUG]由于无障碍辅助app未申请任何权限，导致ColorOS无法解除权限限制](https://github.com/AAswordman/Operit/issues/306) (open)\n - comments: 1 | updated: 2025-12-31T14:13:34Z\n- #300 [部分国行应用获取页面信息不正确](https://github.com/AAswordman/Operit/issues/300) (open)\n - comments: 2 | updated: 2025-12-31T01:56:23Z\n- #295 [记忆与记忆之间的链接只有创建和删除，没有修改](https://github.com/AAswordman/Operit/issues/295) (open)\n - comments: 1 | updated: 2025-12-21T02:08:50Z\n- #273 [建议上架到fdroid](https://github.com/AAswordman/Operit/issues/273) (open)\n - comments: 3 | updated: 2025-12-19T13:05:17Z\n- #291 [导入聊天记录报错](https://github.com/AAswordman/Operit/issues/291) (open)\n - comments: 0 | updated: 2025-12-18T08:22:29Z\n- #287 [【Request】对话绑定模型配置](https://github.com/AAswordman/Operit/issues/287) (open)\n - comments: 1 | updated: 2025-12-17T17:39:36Z\n- #283 [Bug: 无障碍服务已开启但AI助手接口服务显示未连接](https://github.com/AAswordman/Operit/issues/283) (open)\n - comments: 1 | updated: 2025-12-17T17:37:25Z\n- #267 [功能建议：操作屏幕录制、绘图功能、TIM适配等四大功能增强](https://github.com/AAswordman/Operit/issues/267) (open)\n - comments: 1 | updated: 2025-12-11T03:10:36Z\n- #265 [功能建议——安静模式](https://github.com/AAswordman/Operit/issues/265) (open)\n - comments: 1 | updated: 2025-12-11T02:17:10Z\n- #268 [全屏编辑提示词等内容时底部不会被输入法抬起](https://github.com/AAswordman/Operit/issues/268) (open)\n - comments: 0 | updated: 2025-12-10T01:08:33Z\n- #266 [角色切换后主界面历史对话不显示，仅在悬浮窗显示](https://github.com/AAswordman/Operit/issues/266) (open)\n - comments: 3 | updated: 2025-12-08T11:40:49Z\n- #264 [功能建议--变量](https://github.com/AAswordman/Operit/issues/264) (open)\n - comments: 1 | updated: 2025-12-07T11:38:13Z\n- #250 [一些建议和发现的问题](https://github.com/AAswordman/Operit/issues/250) (open)\n - comments: 6 | updated: 2025-12-07T09:21:04Z\n- #263 [搜索引擎使用结果提取的问题](https://github.com/AAswordman/Operit/issues/263) (open)\n - comments: 0 | updated: 2025-12-07T09:13:08Z\n- #258 [为什么请求不到llama.cpp啊](https://github.com/AAswordman/Operit/issues/258) (open)\n - comments: 1 | updated: 2025-11-22T07:56:22Z\n- #237 [建议](https://github.com/AAswordman/Operit/issues/237) (open)\n - labels: enhancement | comments: 3 | updated: 2025-11-12T06:07:20Z\n- #248 [小功能拓展建议](https://github.com/AAswordman/Operit/issues/248) (open)\n - comments: 0 | updated: 2025-11-08T05:35:45Z\n- #216 [Local llm implementation cpu/gpu/npu](https://github.com/AAswordman/Operit/issues/216) (open)\n - comments: 1 | updated: 2025-10-20T04:43:49Z\n- #214 [关于悬浮窗的建议](https://github.com/AAswordman/Operit/issues/214) (open)\n - comments: 0 | updated: 2025-10-15T00:55:58Z\n- #10 [十条建议](https://github.com/AAswordman/Operit/issues/10) (open)\n - labels: enhancement, good first issue | comments: 29 | updated: 2025-10-12T17:22:26Z\n- #165 [code_runner中的代码显示bug](https://github.com/AAswordman/Operit/issues/165) (open)\n - comments: 1 | updated: 2025-08-29T17:23:20Z\n- #138 [建议](https://github.com/AAswordman/Operit/issues/138) (open)\n - comments: 5 | updated: 2025-08-06T14:56:10Z\n- #125 [ui信息始终是Operit AI应用的](https://github.com/AAswordman/Operit/issues/125) (open)\n - comments: 8 | updated: 2025-08-03T17:03:38Z\n- #115 [小建议](https://github.com/AAswordman/Operit/issues/115) (open)\n - comments: 4 | updated: 2025-07-05T02:40:07Z\n- #35 [请增加识图找图功能，解决UI Automator识别不了画布上的自定义组件的缺陷。](https://github.com/AAswordman/Operit/issues/35) (open)\n - comments: 1 | updated: 2025-07-04T16:25:28Z\n- #108 [建议和bug](https://github.com/AAswordman/Operit/issues/108) (open)\n - comments: 8 | updated: 2025-07-02T04:58:07Z\n- #107 [几条建议](https://github.com/AAswordman/Operit/issues/107) (open)\n - labels: enhancement | comments: 1 | updated: 2025-06-30T18:05:48Z\n- #101 [[bug] UI调试工具无法获取当前屏幕内容](https://github.com/AAswordman/Operit/issues/101) (open)\n - comments: 1 | updated: 2025-06-28T10:09:36Z\n- #90 [能否在工具箱中添加一个查看触摸坐标的功能](https://github.com/AAswordman/Operit/issues/90) (open)\n - comments: 1 | updated: 2025-06-22T05:22:40Z\n- #78 [一些建议](https://github.com/AAswordman/Operit/issues/78) (open)\n - comments: 8 | updated: 2025-06-20T15:03:01Z\n- #67 [Miui 14.0.4 在debugger和root模式下均无法获取页面元素](https://github.com/AAswordman/Operit/issues/67) (open)\n - labels: bug | comments: 12 | updated: 2025-06-20T11:06:01Z\n- #27 [屏幕识别在某个软件里识别不出来东西](https://github.com/AAswordman/Operit/issues/27) (open)\n - comments: 1 | updated: 2025-06-07T05:38:57Z\n","tools/adb/JS_ADB_README.md":"# ADB JavaScript Executor\n\nThis repo's ADB JS executors are the main **device-side JavaScript runtime launchers** for Operit.\n\nThey are used for:\n\n- directly running JS on a real Android device during development\n- debugging exported JS functions without a full package import cycle\n- validating sandbox runtime behavior and structured results\n- running JS bridge / script-mode / smoke tests from `app/src/androidTest/js`\n- reproducing device-only runtime bugs quickly\n\nFor direct whole-script execution without specifying an exported function, use `run_sandbox_script.sh` / `run_sandbox_script.bat`.\n\n## Features\n\n- Push JavaScript files to Android devices using ADB\n- Run JS directly inside the Operit Android runtime\n- Execute specified JavaScript functions\n- Execute complete sandbox scripts\n- Execute a whole JS directory with local module dependencies\n- Support for JSON parameter passing\n- Temporary file option (auto-deletion after execution)\n- Implementations in Shell script, Windows Batch file, and Python script\n- **Device selection for multi-device setups**\n- Structured result capture instead of fragile log scraping\n- Useful as both a **runtime debugging launcher** and a **JS bridge test harness**\n\n## Tool Roles\n\nIn this repo, the following tools form the main on-device JS execution workflow:\n\n- `tools/adb/execute_js.bat` / `tools/adb/execute_js.sh`\n The main single-file runtime launcher.\n Pushes one JS file to the Android device and executes an exported function inside the Operit runtime.\n This is the most direct tool for device-side JS debugging.\n- `tools/adb/execute_js_dir.bat` / `tools/adb/execute_js_dir.sh`\n The directory-entry launcher.\n Bundles and runs a JS entry from a directory, so local `require(...)` chains and test suites work.\n- `tools/adb/run_sandbox_script.bat` / `tools/adb/run_sandbox_script.sh`\n The script-mode launcher.\n Runs top-level sandbox script code directly instead of calling an exported function.\n\nThis makes them suitable for:\n\n- directly running and debugging JS on Android\n- validating `JsEngine` behavior on a real device\n- reproducing package/runtime bugs quickly\n- debugging package tools without a full app rebuild loop\n- running JS-side contract tests and smoke tests under `app/src/androidTest/js`\n\n## JS Test Suites In This Repo\n\nThe directory [app/src/androidTest/js](/d:/Code/prog/assistance/app/src/androidTest/js) contains real JS runtime tests and probes, including:\n\n- bridge contract tests\n- bridge edge-case tests\n- script-mode contract tests\n- browser tool smoke tests\n- ffmpeg / utility probes\n\nRepresentative locations:\n\n- [app/src/androidTest/js/com/ai/assistance/operit/core/tools/javascript/bridge_contract](/d:/Code/prog/assistance/app/src/androidTest/js/com/ai/assistance/operit/core/tools/javascript/bridge_contract)\n- [app/src/androidTest/js/com/ai/assistance/operit/core/tools/javascript/bridge_edges](/d:/Code/prog/assistance/app/src/androidTest/js/com/ai/assistance/operit/core/tools/javascript/bridge_edges)\n- [app/src/androidTest/js/com/ai/assistance/operit/core/tools/javascript/script_mode_contract](/d:/Code/prog/assistance/app/src/androidTest/js/com/ai/assistance/operit/core/tools/javascript/script_mode_contract)\n- [app/src/androidTest/js/com/ai/assistance/operit/core/tools/defaultTool/standard/browser/main.js](/d:/Code/prog/assistance/app/src/androidTest/js/com/ai/assistance/operit/core/tools/defaultTool/standard/browser/main.js)\n- [app/src/androidTest/js/com/ai/assistance/operit/util/ttscleaner/ttscleaner.js](/d:/Code/prog/assistance/app/src/androidTest/js/com/ai/assistance/operit/util/ttscleaner/ttscleaner.js)\n\n## Quick Choice\n\nIf you just want the short answer for \"which tool should I use\":\n\n- Use `execute_js.*` when you want to call one exported function from one normal `.js` file\n- Use `execute_js_dir.*` when the entry depends on sibling modules, or when you are running directory-based tests under `app/src/androidTest/js`\n- Use `run_sandbox_script.*` when you want top-level script-mode execution instead of calling an exported function\n- Use `tools/example_packages/sync_example_packages.py` when you changed an `examples/` package or toolpkg and want it synced into the real package-loading path\n- If you are debugging `operit_editor` tools such as `debug_install_toolpkg`, the usual flow is: sync with `tools/example_packages/sync_example_packages.py`, then call the debug tool with `execute_js.bat`\n\n## Prerequisites\n\n- Android SDK (ADB)\n- Android device with USB debugging enabled\n- ADB debugging permission granted on the device\n- Your application installed on the device\n\n## Quick Start\n\n### Using Shell Script (Linux/macOS)\n\n1. Make the script executable:\n```bash\nchmod +x execute_js.sh\n```\n\n2. Execute the script:\n```bash\n./execute_js.sh path/to/your/script.js functionName '{\"param1\":\"value1\"}'\n```\n\n3. Execute a whole sandbox script directly:\n```bash\n./run_sandbox_script.sh path/to/your/script.js '{\"param1\":\"value1\"}'\n```\n\n### Using Batch Script (Windows)\n\n1. Execute the batch file:\n```cmd\nexecute_js.bat path\\to\\your\\script.js functionName @params.json\n```\n\n2. Execute a whole sandbox script directly:\n```cmd\nrun_sandbox_script.bat path\\to\\your\\script.js @params.json\n```\n\n### Execute A Whole Directory (supports `require(...)`)\n\nSometimes a script needs `require('./helper')`, shared local modules, or a whole test suite layout.\nThe single-file executors only push one JS file, so this repo also provides directory-based executors.\n\nWindows:\n```cmd\ntools\\adb\\execute_js_dir.bat app\\src\\androidTest\\js com\\ai\\assistance\\operit\\util\\ttscleaner\\main.js run \"{}\"\n```\n\nLinux/macOS:\n```bash\n./tools/adb/execute_js_dir.sh app/src/androidTest/js com/ai/assistance/operit/util/ttscleaner/ttscleaner.js run '{}'\n```\n\nMore realistic examples:\n\n```cmd\ntools\\adb\\execute_js_dir.bat app\\src\\androidTest\\js com\\ai\\assistance\\operit\\core\\tools\\javascript\\bridge_contract\\bridge_contract_runner.js run @params.json\ntools\\adb\\execute_js_dir.bat app\\src\\androidTest\\js com\\ai\\assistance\\operit\\core\\tools\\defaultTool\\standard\\browser\\main.js run \"{}\"\n```\n\nYou can still pass inline JSON directly. The scripts now write that JSON into a temporary file and push it to the device, which avoids the old `adb shell am broadcast --es params ...` quoting breakage. On PowerShell, prefer single-quoted JSON like `'{\"param1\":\"value1\"}'` or use `@params.json`.\n\n### Using Python Script (Cross-platform)\n\n1. Ensure Python 3 is installed\n\n2. Execute the script:\n```bash\npython execute_js.py path/to/your/script.js functionName --params '{\"param1\":\"value1\"}'\n```\n\n3. Additional options:\n```bash\n# Specify a device directly (skip device selection prompt)\npython execute_js.py path/to/script.js functionName --device DEVICE_SERIAL\n\n# Keep the file on the device after execution\npython execute_js.py path/to/script.js functionName --keep\n```\n\n## Device Selection\n\nWhen multiple devices are connected:\n\n1. The script will display a list of available devices\n2. Enter the number corresponding to your target device\n3. All ADB operations will be performed on the selected device\n\nExample:\n```\nChecking connected devices...\n1: emulator-5554\n2: 192.168.1.100:5555\nEnter device number (1-2): \n```\n\n## Examples\n\n### 1. Execute the greeting function\n\n```bash\n# Linux/macOS\n./execute_js.sh test_script.js sayHello '{\"name\":\"John\"}'\n\n# Windows\nexecute_js.bat test_script.js sayHello @params.json\n\n# Python (any platform)\npython execute_js.py test_script.js sayHello --params '{\"name\":\"John\"}'\n```\n\n### 2. Execute the calculation function\n\n```bash\n# Linux/macOS\n./execute_js.sh test_script.js calculate '{\"num1\":10,\"num2\":5,\"operation\":\"multiply\"}'\n\n# Windows\nexecute_js.bat test_script.js calculate @params.json\n\n# Python (any platform)\npython execute_js.py test_script.js calculate --params '{\"num1\":10,\"num2\":5,\"operation\":\"multiply\"}'\n```\n\n## Viewing Execution Results\n\nThe executor now waits for a dedicated structured result file instead of scraping `adb logcat`.\nAfter execution it prints a JSON payload containing:\n\n- `success`\n- `result`\n- `error`\n- `events` (including `console.log/info/warn/error` and intermediate updates)\n- `durationMs`\n\nThis is especially useful for JS runtime tests, because failures come back as structured payloads rather than \"check logcat manually\".\n\nYou can adjust the wait timeout with:\n\n```bash\nOPERIT_RESULT_WAIT_SECONDS=30 ./execute_js.sh path/to/your/script.js functionName '{\"param1\":\"value1\"}'\n```\n\n## Sandbox Script Debug Notes\n\nWhen you use `run_sandbox_script.sh` / `run_sandbox_script.bat`, or call package tools such as `operit_editor:debug_run_sandbox_script` with `source_code`, the code is executed as a **top-level script snippet**, not as `function(params) { ... }`.\n\nThat means:\n\n- Use `console.log(...)`, `console.info(...)`, `console.warn(...)`, `console.error(...)` for logs\n- Use `emit(...)` to send intermediate events\n- Use `return result` or `complete(...)` to finish with a structured result\n- Do **not** assume `params` is directly available inside `source_code`\n- Do **not** call `intermediate(...)`; the supported helper name is `emit(...)`\n\nRecommended inline snippet:\n\n```javascript\nconsole.log(\"inline debug start\");\nemit({ stage: \"inline\", ok: true });\ncomplete({\n success: true,\n message: \"inline debug finished\"\n});\n```\n\nIf you need parameter-driven logic, prefer one of these approaches:\n\n- Use `execute_js.*` and call an exported function like `function myFunc(params) { ... }`\n- Use `debug_run_sandbox_script` with `source_path` and put the logic in a real script file\n- Keep `source_code` for quick top-level smoke tests, logging, and minimal one-off checks\n\n## Purpose And Invocation\n\n### 1. What `execute_js.*` is for\n\nThis is the most direct Android-side JS runner.\n\nYou give it:\n\n- one JS file\n- one exported function name\n- one JSON parameter payload\n\nIt pushes that file to the device and calls that function inside Operit's Android JS runtime.\n\nUse it for:\n\n- single-file behavior checks\n- direct exported-function debugging\n- reproducing runtime-only device errors\n- debugging one tool implementation inside a package\n\nMost common usage:\n\n```cmd\ntools\\adb\\execute_js.bat examples\\operit_editor.js debug_install_toolpkg @params.json\n```\n\nMinimum file requirements:\n\n- the file must be valid JavaScript, not raw TypeScript\n- the target function must be exported\n- params must be passed as JSON\n\nExample:\n\n```javascript\nfunction main(params) {\n return {\n success: true,\n echo: params\n };\n}\n\nexports.main = main;\n```\n\n### 2. What `execute_js_dir.*` is for\n\nThis is the directory-entry runner.\n\nIf your entry file is not standalone and depends on local modules through `require(\"./x\")`, sibling helpers, shared runners, or directory-local test harnesses, switch to this instead of forcing the single-file runner.\n\nUse it for:\n\n- test entries under `app/src/androidTest/js`\n- bridge contract / browser smoke / harness-style test directories\n- any new multi-file JS runtime test suite you add\n\nMost common usage:\n\n```cmd\ntools\\adb\\execute_js_dir.bat app\\src\\androidTest\\js com\\ai\\assistance\\operit\\core\\tools\\javascript\\bridge_contract\\bridge_contract_runner.js run @params.json\n```\n\nCall format:\n\n```cmd\ntools\\adb\\execute_js_dir.bat [JSON params|@params_file]\n```\n\nThe key points are:\n\n- the first argument is the suite root\n- the second argument is the entry path relative to that root\n- the third argument is usually a runner function such as `run`\n\n### 3. What `run_sandbox_script.*` is for\n\nThis does not call an exported function. It runs the whole file as a top-level script.\n\nUse it for:\n\n- script-mode contract checks\n- quick `emit(...)` verification\n- quick `complete(...)` verification\n- temporary runtime probe scripts\n\nMost common usage:\n\n```cmd\ntools\\adb\\run_sandbox_script.bat temp\\probe.js @params.json\n```\n\nIf your code is naturally top-level script logic, this is usually simpler than wrapping everything in `exports.main = ...`.\n\n### 4. What `tools/example_packages/sync_example_packages.py` is for\n\nThis is not just a copy script. It is the sync entrypoint for `examples/` package development.\n\nIts main jobs are:\n\n- prebuild relevant TypeScript under `examples/` into JS\n- pack manifest-based directories into `.toolpkg`\n- sync normal `.js` or `.toolpkg` outputs into `app/src/main/assets/packages`\n- hot-reload changed packages to a connected device when available\n\nUse it when:\n\n- you changed a real package under `examples/`\n- you want package-management, sandbox package lists, or built-in loading logic to see the latest output\n- you want to validate the folder -> `.toolpkg` -> debug install path\n\nMost common usage:\n\n```cmd\nd:\\Code\\prog\\assistance\\.venv\\Scripts\\python.exe d:\\Code\\prog\\assistance\\tools\\example_packages\\sync_example_packages.py --include sidebar_bing_action\n```\n\nTo sync all syncable example items for broad validation:\n\n```cmd\nd:\\Code\\prog\\assistance\\.venv\\Scripts\\python.exe d:\\Code\\prog\\assistance\\tools\\example_packages\\sync_example_packages.py --mode test\n```\n\nTo update local assets without device hot reload:\n\n```cmd\nd:\\Code\\prog\\assistance\\.venv\\Scripts\\python.exe d:\\Code\\prog\\assistance\\tools\\example_packages\\sync_example_packages.py --include sidebar_bing_action --no-hot-reload\n```\n\n## How To Add Tests\n\nThe easy thing to get wrong is assuming every kind of test belongs in the same place. They do not.\n\n### 1. Add a single-file function test\n\nIf you only want to verify one function's logic, the lightest approach is:\n\n- write a normal JS file\n- export `main` or `run`\n- call it with `execute_js.*`\n\nThis is best for:\n\n- small logic checks\n- parameter parsing checks\n- return-shape checks\n- minimal bug reproductions\n\n### 2. Add a directory-based runtime test\n\nIf the test needs multiple local modules, put it under [app/src/androidTest/js](/d:/Code/prog/assistance/app/src/androidTest/js) and organize it as a small directory-based suite.\n\nRecommended shape:\n\n- one runner file such as `xxx_runner.js`\n- a few test files or helpers\n- the runner exports `run(params)`\n\nThen call it with:\n\n```cmd\ntools\\adb\\execute_js_dir.bat app\\src\\androidTest\\js run \"{}\"\n```\n\nThis is best for:\n\n- bridge contract tests\n- multi-module coordination\n- real runtime smoke tests\n- anything that needs local `require(...)`\n\n### 3. Add a script-mode test\n\nIf what you need to verify is:\n\n- top-level `return`\n- `emit(...)`\n- `complete(...)`\n- differences between script mode and function mode\n\nthen do not force it into an exported-function test. Write it as a script-mode file and run it with `run_sandbox_script.*`.\n\n### 4. Add validation for an `examples/` package or toolpkg\n\nIf you are adding a real package that should be loaded by the package system, the point is not only \"can this JS run\" but also \"can this package be synced, refreshed, installed, and recognized\".\n\nRecommended approach:\n\n- add or modify the `.ts`, `.js`, or manifest-based directory under `examples/`\n- if it is a directory-based package, make sure it has `manifest.json` or `manifest.hjson`\n- run `tools/example_packages/sync_example_packages.py`\n- then use `execute_js.bat` to call related debug tools, or validate inside the app\n\nIn other words:\n\n- the runners test whether JS executes correctly inside the Android runtime\n- `tools/example_packages/sync_example_packages.py` tests whether the `examples/` package enters the real package-loading path correctly\n\n## How To Use It With `tools/example_packages/sync_example_packages.py`\n\n### Scenario 1: You changed a normal JS script\n\nIn this case you usually do not need sync first.\n\nJust run:\n\n```cmd\ntools\\adb\\execute_js.bat path\\to\\script.js main @params.json\n```\n\nbecause you are validating script logic, not package loading.\n\n### Scenario 2: You changed a package under `examples/`\n\nRecommended order:\n\n1. Edit `examples/...`\n2. Run `tools/example_packages/sync_example_packages.py`\n3. Confirm the outputs were synced into `app/src/main/assets/packages`\n4. If a device is connected, also validate hot reload\n5. Then verify behavior inside the app or through debug tools\n\nThis fits:\n\n- normal `.js` packages\n- example packages that should appear in package lists\n- changes to package description, manifest, or dependency structure\n\n### Scenario 3: You changed a directory-based toolpkg\n\nThis is the case that most needs `tools/example_packages/sync_example_packages.py`.\n\nRecommended order:\n\n1. Edit `examples/`\n2. Run `tools/example_packages/sync_example_packages.py --include `\n3. Let it pack the directory into `.toolpkg`\n4. Let it sync the generated artifact into assets and the device\n5. Then verify installation through `operit_editor`'s `debug_install_toolpkg` or a related debug entry\n\nThis validates the full chain:\n\n- whether the directory packs correctly\n- whether the `.toolpkg` hot-reloads to device correctly\n- whether debug install recognizes it\n- whether the refreshed package actually enters the loading list\n\n### Scenario 4: You changed a debug tool such as `operit_editor`\n\nRecommended order:\n\n1. Sync `operit_editor` itself with `tools/example_packages/sync_example_packages.py`\n2. Prepare the package or toolpkg you want it to install\n3. Call the debug function through `execute_js.bat`\n4. Inspect the structured result for success, failure, and related warnings\n\nExample:\n\n```cmd\nd:\\Code\\prog\\assistance\\.venv\\Scripts\\python.exe d:\\Code\\prog\\assistance\\tools\\example_packages\\sync_example_packages.py --include operit_editor --include sidebar_bing_action\ntools\\adb\\execute_js.bat examples\\operit_editor.js debug_install_toolpkg @params.json\n```\n\nThis is good for validating:\n\n- whether the debug install call shape is correct\n- whether a folder packaged into `.toolpkg` installs correctly\n- whether install-time warnings or errors are returned back to the caller\n\n## Recommended Workflows\n\n### 1. Direct Android-side JS debugging\n\nUse `execute_js.bat` / `execute_js.sh` when you want to directly run and debug one JS file on the Android device.\nThis is the default choice for ordinary sandbox/package JS development.\n\n```cmd\ntools\\adb\\execute_js.bat examples\\operit_editor.js debug_install_toolpkg @params.json\n```\n\nTypical use cases:\n\n- test one exported function quickly\n- reproduce a runtime bug on device\n- verify parameter parsing / `complete(...)` / structured output\n- debug a normal `.js` package before turning it into something larger\n\n### 2. Real test suite / local-module run\n\nUse `execute_js_dir.*` when the entry file depends on sibling modules or you are running material under `app/src/androidTest/js`.\n\n```cmd\ntools\\adb\\execute_js_dir.bat app\\src\\androidTest\\js com\\ai\\assistance\\operit\\core\\tools\\javascript\\script_mode_contract\\return_object.js run \"{}\"\n```\n\n### 3. Direct sandbox snippet probe\n\nUse `run_sandbox_script.*` for quick script-mode behavior checks.\n\n```cmd\ntools\\adb\\run_sandbox_script.bat temp\\probe.js @params.json\n```\n\n## Quick Command List\n\n### 1. Run one normal exported function\n\n```cmd\ntools\\adb\\execute_js.bat examples\\my_script.js main @params.json\n```\n\n### 2. Run one `androidTest/js` directory-based test entry\n\n```cmd\ntools\\adb\\execute_js_dir.bat app\\src\\androidTest\\js com\\ai\\assistance\\operit\\core\\tools\\javascript\\bridge_contract\\bridge_contract_runner.js run @params.json\n```\n\n### 3. Run one top-level script-mode probe\n\n```cmd\ntools\\adb\\run_sandbox_script.bat temp\\probe.js @params.json\n```\n\n### 4. Sync one `examples/` package into assets and device\n\n```cmd\nd:\\Code\\prog\\assistance\\.venv\\Scripts\\python.exe d:\\Code\\prog\\assistance\\tools\\example_packages\\sync_example_packages.py --include sidebar_bing_action\n```\n\n### 5. Sync first, then call the debug installer tool\n\n```cmd\nd:\\Code\\prog\\assistance\\.venv\\Scripts\\python.exe d:\\Code\\prog\\assistance\\tools\\example_packages\\sync_example_packages.py --include operit_editor --include sidebar_bing_action\ntools\\adb\\execute_js.bat examples\\operit_editor.js debug_install_toolpkg @params.json\n```\n\n## JavaScript File Requirements\n\n- Files must be valid JavaScript (TypeScript not supported)\n- Functions must be exported (using `exports.functionName = functionName`)\n- Functions must accept a params parameter (containing the passed parameters)\n- Functions can either `return result` directly or call `complete(result)`\n\n## Required Function Example\n\n```javascript\nfunction myFunction(params) {\n // Process parameters\n const name = params.name || \"default\";\n \n // Execute business logic\n const result = `Result: ${name}`;\n \n // Return result\n return {\n success: true,\n result: result\n };\n}\n\n// Export function\nexports.myFunction = myFunction;\n```\n\n## Technical Details\n\n1. The Shell/Batch script pushes the JavaScript file to a temporary directory on the device\n2. `execute_js.bat` / `execute_js.sh` directly execute that pushed file inside the Android app's JS runtime\n3. `execute_js_dir.*` bundles a directory entry first, so local modules can be resolved in one pushed artifact\n4. Inline JSON parameters are first written to a temp JSON file, then pushed to the device as `params_file_path`\n5. An ADB broadcast is sent to the application with the execution request\n6. The application's BroadcastReceiver receives the request and uses `JsEngine` to execute the function or whole script\n7. Execution results are written to a dedicated JSON file on the device\n8. The executor waits for that file, prints it, and then cleans it up\n\n## Troubleshooting\n\n### Common Issues\n\n1. **ADB command not found** \n Ensure the Android SDK's platform-tools directory is in your PATH environment variable.\n\n2. **No devices detected**\n - Make sure the device is connected\n - Ensure USB debugging is enabled\n - Check that the computer is authorized for USB debugging\n\n3. **Broadcast sent but function not executed**\n - Check the logs for error messages\n - Confirm the application is running\n - Verify the receiver is correctly registered\n\n4. **JavaScript errors**\n - Check for TypeScript-specific syntax (like type annotations)\n - Ensure functions are properly exported\n - Verify parameter formats are correct\n \n## Required Permissions\n\nThis feature requires the following permissions:\n\n- Read and write external storage\n- Permission to receive broadcasts\n\n## Security Considerations\n\n- This feature should only be used for development and debugging purposes\n- In production environments, this feature should be disabled or restricted to prevent security risks \n","tools/compose_dsl/COMPOSE_DSL_DEBUG_README.md":"# Compose DSL UI Dump\n\n## 用途\n\n`dump_current_compose_dsl_ui.bat` 用来抓取当前正在显示的 `compose_dsl` 页面运行时快照，方便排查：\n\n- 脚本输出的组件树是否正确\n- 宿主解析后的树是否一致\n- 布局坐标和尺寸是否符合预期\n- 当前页面 `state` / `memo` 是否异常\n\n这套工具适合排查“结构看起来对，但界面显示不对”的问题。\n\n## 使用方法\n\n1. 用宿主打开你要调试的 `compose_dsl` 页面。\n2. 等页面进入你想观察的状态。\n3. 运行：\n\n```bat\nd:\\Code\\prog\\assistance\\tools\\compose_dsl\\dump_current_compose_dsl_ui.bat\n```\n\n## 前提条件\n\n- 已安装并可使用 `adb`\n- 至少连接了一台可调试设备\n- 设备上的宿主版本已经包含当前调试导出逻辑\n- 设备上已安装 `com.ai.assistance.operit.debug` 或 `com.ai.assistance.operit`；脚本未指定时优先使用 Debug 包\n\n如果连接了多台设备，脚本会提示选择目标设备。\n\n如果 Debug 和 Release APK 同时安装，可以用环境变量指定目标：\n\n```bat\nset OPERIT_APP_PACKAGE=com.ai.assistance.operit\nd:\\Code\\prog\\assistance\\tools\\compose_dsl\\dump_current_compose_dsl_ui.bat\n```\n\n## 导出位置\n\n脚本会把文件拉回本地目录：\n\n```text\nd:\\Code\\prog\\assistance\\debug_output\\compose_dsl_dump\\<时间戳>\\\n```\n\n例如：\n\n```text\nd:\\Code\\prog\\assistance\\debug_output\\compose_dsl_dump\\20260425-153457\\\n```\n\n## 文件说明\n\n- `dump_manifest.json`\n 当前页面的基础信息，包括包名、模块名、phase、是否仍在 loading / dispatching。\n\n- `source_script.js`\n 当前页面实际执行的 UI 脚本源码。\n\n- `raw_render_result.txt`\n JS 原始 render 返回值的文本形式。\n\n- `raw_render_result.json`\n 如果原始返回值可以解析为 JSON，这里会保存格式化后的版本。\n\n- `parsed_render_result.json`\n 宿主解析后的完整 render 结果。\n\n- `compose_tree.txt`\n 解析后的组件树，可快速看结构。\n\n- `compose_tree.json`\n 组件树的 JSON 形式。\n\n- `layout_nodes.txt`\n 每个节点的真实布局信息，包括 `x / y / width / height`。\n\n- `layout_nodes.json`\n 布局信息的 JSON 形式。\n\n- `compose_layout_tree.txt`\n “组件树 + 布局信息”合并后的可读版本。\n\n- `state.json`\n 当前页面状态。\n\n- `memo.json`\n 当前页面 memo。\n\n## 推荐排查顺序\n\n1. 先看 `dump_manifest.json`\n 确认抓到的是不是当前页面，以及页面是不是已经稳定。\n\n2. 再看 `compose_tree.txt`\n 判断脚本输出结构是否正确。\n\n3. 再看 `layout_nodes.txt` 或 `compose_layout_tree.txt`\n 判断真实布局是不是出了问题。\n\n4. 如果怀疑状态异常，再看 `state.json`\n 确认是不是脚本状态导致界面不对。\n\n5. 如果怀疑宿主解析有偏差，再对比：\n `raw_render_result.json` 和 `parsed_render_result.json`\n\n## 常见场景\n\n- 文本、图标、按钮没有居中\n- `weight`、`fillMaxWidth`、`padding` 没按预期生效\n- `onLoad` 后页面状态和预期不一致\n- 脚本写出来的树和宿主最终理解的树不同\n\n## 注意事项\n\n- 这套工具抓的是“当前正在显示的页面快照”，不是历史页面。\n- 如果页面还在频繁重组或异步加载，建议等稳定后再抓一次。\n- 如果宿主调试导出逻辑有更新，需要重新安装宿主后才能看到新导出字段。\n","tools/compose_dsl/README.md":"# compose_dsl artifact generator\n\nGenerates compose_dsl artifacts from Compose source jars in Gradle cache.\n\n- Kotlin renderer registry:\n - `app/src/main/java/com/ai/assistance/operit/ui/common/composedsl/ToolPkgComposeDslGeneratedRegistry.kt`\n- Kotlin renderers:\n - `app/src/main/java/com/ai/assistance/operit/ui/common/composedsl/ToolPkgComposeDslGeneratedRenderers.kt`\n- TypeScript generated bindings:\n - `examples/types/compose-dsl.material3.generated.d.ts`\n\nRun:\n\n```bash\npython tools/compose_dsl/generate_compose_dsl_artifacts.py\n```\n\nNotes:\n- Source jars are resolved from `~/.gradle/caches/modules-2/files-2.1`.\n- If jars are missing, sync/build once to download dependencies.\n- Generator behavior:\n - Keeps dedicated renderers for core complex nodes (TextField/Icon/Card/Surface, etc.).\n - Auto-discovers additional public `@Composable` functions from Material3/Foundation and\n generates generic renderers/registry/TS props when required params are mappable.\n - `ToolPkgComposeDslGeneratedRenderers.kt.tpl` is now a thin scaffold with helper functions;\n component renderers are injected at `// __GENERATED_COMPONENT_RENDERERS__`.\n","tools/adb/JS_ADB_README_zh.md":"# ADB JavaScript 执行与调试说明\n\n这套 ADB JS 脚本不是单纯的“把一个文件推到手机上跑一下”。\n在 Operit 仓库里，它们是主要的 **安卓端 JavaScript 运行、调试与验证入口**。\n\n它们适合用于：\n\n- 直接把 JS 推到真实 Android 设备上运行\n- 在不走完整导入流程时调试普通 `.js` sandbox / package\n- 验证导出函数的参数传递、返回值、`complete(...)`、结构化结果\n- 复现只能在设备侧出现的运行时问题\n- 运行 `app/src/androidTest/js` 下的 JS bridge / script mode / smoke test 资产\n\n如果你要直接执行“顶层脚本模式”，而不是调用导出函数，请使用 `run_sandbox_script.sh` / `run_sandbox_script.bat`。\n\n## 工具分工\n\n### `tools/adb/execute_js.bat` / `tools/adb/execute_js.sh`\n\n这是最常用的单文件运行器。\n\n作用：\n\n- 把一个 JS 文件临时推到设备\n- 在 Operit 的 Android JS runtime 里调用某个导出函数\n- 返回结构化结果\n\n适合：\n\n- 普通单文件 JS 调试\n- 快速验证某个函数逻辑\n- 复现设备侧 bug\n- 开发普通 `.js` package 时做单次验证\n\n### `tools/adb/execute_js_dir.bat` / `tools/adb/execute_js_dir.sh`\n\n这是目录入口运行器。\n\n作用：\n\n- 以目录为单位执行入口文件\n- 先做 bundle，再推送到设备\n- 支持本地 `require(...)` / 多文件依赖\n\n适合：\n\n- 入口依赖多个本地模块\n- 运行 `app/src/androidTest/js` 里的测试入口\n- 跑 browser / bridge / harness 一类目录化测试\n\n### `tools/adb/run_sandbox_script.bat` / `tools/adb/run_sandbox_script.sh`\n\n这是脚本模式运行器。\n\n作用：\n\n- 直接执行顶层 sandbox script\n- 不要求导出函数\n- 适合验证 script mode 合约\n\n适合：\n\n- 快速跑一段顶层脚本\n- 验证 `emit(...)` / `complete(...)` / `return`\n- 做 inline snippet / top-level 行为测试\n\n## 真实测试资产\n\n仓库里的 [app/src/androidTest/js](/d:/Code/prog/assistance/app/src/androidTest/js) 不是普通示例目录，而是这套工具的重要使用场景之一。\n\n其中包括：\n\n- JS bridge contract 测试\n- JS bridge edge case 测试\n- script mode contract 测试\n- browser tool smoke / probe\n- utility / ffmpeg / ttscleaner 等运行时测试资产\n\n典型目录：\n\n- [bridge_contract](/d:/Code/prog/assistance/app/src/androidTest/js/com/ai/assistance/operit/core/tools/javascript/bridge_contract)\n- [bridge_edges](/d:/Code/prog/assistance/app/src/androidTest/js/com/ai/assistance/operit/core/tools/javascript/bridge_edges)\n- [script_mode_contract](/d:/Code/prog/assistance/app/src/androidTest/js/com/ai/assistance/operit/core/tools/javascript/script_mode_contract)\n- [browser main.js](/d:/Code/prog/assistance/app/src/androidTest/js/com/ai/assistance/operit/core/tools/defaultTool/standard/browser/main.js)\n- [ttscleaner.js](/d:/Code/prog/assistance/app/src/androidTest/js/com/ai/assistance/operit/util/ttscleaner/ttscleaner.js)\n\n## 先记结论\n\n如果你只是想快速判断“我现在该用哪个”：\n\n- 调一个普通 `.js` 文件里导出的函数，用 `execute_js.*`\n- 入口文件依赖同目录其他模块，或者你在跑 `app/src/androidTest/js` 里的目录化测试，用 `execute_js_dir.*`\n- 想验证顶层 script mode 行为，不想写导出函数，用 `run_sandbox_script.*`\n- 你改的是 `examples/` 里的 package / toolpkg，想热更新到设备里的包系统，再去 UI 或包管理里验证，用 `tools/example_packages/sync_example_packages.py`\n- 你改的是 `examples/` 里的 toolpkg 调试工具，例如 `operit_editor` 的 `debug_install_toolpkg`，通常是先 `tools/example_packages/sync_example_packages.py`，再用 `execute_js.bat` 去调这个工具\n\n## 快速开始\n\n### Windows：执行单文件导出函数\n\n```cmd\ntools\\adb\\execute_js.bat path\\to\\your\\script.js functionName @params.json\n```\n\n示例：\n\n```cmd\ntools\\adb\\execute_js.bat examples\\operit_editor.js debug_install_toolpkg @params.json\n```\n\n### Linux/macOS：执行单文件导出函数\n\n```bash\n./tools/adb/execute_js.sh path/to/your/script.js functionName '{\"param1\":\"value1\"}'\n```\n\n### 执行整个目录入口（支持 `require(...)`）\n\nWindows：\n\n```cmd\ntools\\adb\\execute_js_dir.bat app\\src\\androidTest\\js com\\ai\\assistance\\operit\\core\\tools\\javascript\\bridge_contract\\bridge_contract_runner.js run @params.json\ntools\\adb\\execute_js_dir.bat app\\src\\androidTest\\js com\\ai\\assistance\\operit\\core\\tools\\defaultTool\\standard\\browser\\main.js run \"{}\"\n```\n\nLinux/macOS：\n\n```bash\n./tools/adb/execute_js_dir.sh app/src/androidTest/js com/ai/assistance/operit/core/tools/javascript/bridge_contract/bridge_contract_runner.js run @params.json\n```\n\n### 执行顶层 sandbox script\n\nWindows：\n\n```cmd\ntools\\adb\\run_sandbox_script.bat temp\\probe.js @params.json\n```\n\nLinux/macOS：\n\n```bash\n./tools/adb/run_sandbox_script.sh temp/probe.js @params.json\n```\n\n## 结果查看\n\n这些执行器现在不是靠 `adb logcat` 抓输出，而是等待设备上的结构化结果文件。\n执行结束后会打印 JSON 结果，通常包含：\n\n- `success`\n- `result`\n- `error`\n- `events`\n- `durationMs`\n\n这对于运行时调试和 JS 合约测试特别有用，因为失败原因会更集中，不需要再手翻大量日志。\n\n可以通过下面的环境变量调整等待超时：\n\n```cmd\nset OPERIT_RESULT_WAIT_SECONDS=30\ntools\\adb\\execute_js.bat examples\\my_script.js main @params.json\n```\n\n### Debug / Release 双包选择\n\n这四个 ADB 执行脚本会同时支持以下两个 Operit applicationId：\n\n- `com.ai.assistance.operit.debug`\n- `com.ai.assistance.operit`\n\n未设置配置时，脚本会查询设备上的已安装包并优先选择 Debug 包；只安装 Release 包时会使用 Release 包。每次执行都会打印最终选择的 applicationId，文件目录和 receiver 都会跟随该值变化。JS 执行 action 固定为 `com.ai.assistance.operit.EXECUTE_JS`，因为它是 Receiver 的跨构建协议，不随 applicationId 追加 `.debug`。\n\n如果两种 APK 同时安装，可以显式指定：\n\n```cmd\nset OPERIT_APP_PACKAGE=com.ai.assistance.operit.debug\ntools\\adb\\execute_js.bat examples\\my_script.js main @params.json\n```\n\nLinux/macOS：\n\n```bash\nOPERIT_APP_PACKAGE=com.ai.assistance.operit.debug ./tools/adb/execute_js.sh examples/my_script.js main '{}'\n```\n\nToolPkg 调试安装器支持同样的环境变量，也支持 `--app-package `；示例包热更新脚本支持同名参数。指定的包必须已经安装在所选设备上。\n\n## 作用和调用方法\n\n### 1. `execute_js.*` 是干什么的\n\n它是最直接的“安卓真机 JS 运行器”。\n\n你给它：\n\n- 一个 JS 文件\n- 一个导出函数名\n- 一份 JSON 参数\n\n它就会把这个文件放到设备上，在 Operit 的 JS runtime 里直接调用这个函数。\n\n适合：\n\n- 单文件功能验证\n- 调某个导出函数\n- 复现设备侧运行时报错\n- 调试 package 里的某个工具实现\n\n最常见调用：\n\n```cmd\ntools\\adb\\execute_js.bat examples\\operit_editor.js debug_install_toolpkg @params.json\n```\n\n你在写新脚本时，最小可运行要求就是：\n\n- 文件是合法 JS，不是 TS 原文\n- 目标函数已经导出\n- 参数按 JSON 传入\n\n例如：\n\n```javascript\nfunction main(params) {\n return {\n success: true,\n echo: params\n };\n}\n\nexports.main = main;\n```\n\n### 2. `execute_js_dir.*` 是干什么的\n\n它是“目录入口执行器”。\n\n如果你的入口文件不是一个孤立文件，而是还会 `require(\"./xxx\")`、依赖同目录工具模块、测试工具、runner、helper，那么不要继续用单文件执行器，直接换这个。\n\n适合：\n\n- `app/src/androidTest/js` 下的测试入口\n- bridge contract / browser smoke / harness 这种目录化测试\n- 你自己新加了一套多文件测试目录\n\n最常见调用：\n\n```cmd\ntools\\adb\\execute_js_dir.bat app\\src\\androidTest\\js com\\ai\\assistance\\operit\\core\\tools\\javascript\\bridge_contract\\bridge_contract_runner.js run @params.json\n```\n\n调用格式：\n\n```cmd\ntools\\adb\\execute_js_dir.bat <根目录> <入口相对路径> <函数名> [JSON参数|@参数文件]\n```\n\n这里最关键的是：\n\n- 第一个参数是“测试根目录”\n- 第二个参数是“相对这个根目录的入口文件”\n- 第三个参数通常是 runner 暴露的 `run`\n\n### 3. `run_sandbox_script.*` 是干什么的\n\n它不是调导出函数，而是直接跑“整段顶层脚本”。\n\n适合：\n\n- 验证 script mode 合约\n- 快速试 `emit(...)`\n- 快速试 `complete(...)`\n- 快速做一段临时探针脚本\n\n最常见调用：\n\n```cmd\ntools\\adb\\run_sandbox_script.bat temp\\probe.js @params.json\n```\n\n如果你的代码天然就是“顶层执行”，这个比先包一层 `exports.main = ...` 更顺手。\n\n### 4. `tools/example_packages/sync_example_packages.py` 是干什么的\n\n它不是单纯的“复制文件脚本”，而是 `examples/` 包开发时的同步入口。\n\n它最重要的作用是：\n\n- 先把 `examples/` 里相关 TS 预编译成 JS\n- 把带 `manifest.json` / `manifest.hjson` 的目录打成 `.toolpkg`\n- 把普通 `.js` 或 `.toolpkg` 同步到 `app/src/main/assets/packages`\n- 如果连着设备，还会把变化的包热更新到设备\n\n所以它适合：\n\n- 你改的是 `examples/` 里的正式包\n- 你想让包管理 / 沙箱包列表 / 内置加载逻辑看到最新结果\n- 你要验证 folder -> `.toolpkg` -> debug install 这条链路\n\n最常见调用：\n\n```cmd\nd:\\Code\\prog\\assistance\\.venv\\Scripts\\python.exe d:\\Code\\prog\\assistance\\tools\\example_packages\\sync_example_packages.py --include sidebar_bing_action\n```\n\n如果你要全量测试 examples 里的可同步项目，可以用：\n\n```cmd\nd:\\Code\\prog\\assistance\\.venv\\Scripts\\python.exe d:\\Code\\prog\\assistance\\tools\\example_packages\\sync_example_packages.py --mode test\n```\n\n如果你只想更新本地资产，不想碰设备热更新：\n\n```cmd\nd:\\Code\\prog\\assistance\\.venv\\Scripts\\python.exe d:\\Code\\prog\\assistance\\tools\\example_packages\\sync_example_packages.py --include sidebar_bing_action --no-hot-reload\n```\n\n## 测试如何加\n\n这里最容易混淆的是：并不是所有“测试”都要放到同一个地方。\n\n### 1. 加单文件函数测试\n\n如果你只是想验证一个函数逻辑是否正确，最轻量的方式是：\n\n- 先写一个普通 JS 文件\n- 导出一个 `main` 或 `run`\n- 用 `execute_js.*` 直接调\n\n这种方式适合：\n\n- 小逻辑验证\n- 参数解析验证\n- 返回结构验证\n- 某个 bug 的最小复现\n\n### 2. 加目录化运行时测试\n\n如果你的测试会引用多个本地模块，建议直接放到 [app/src/androidTest/js](/d:/Code/prog/assistance/app/src/androidTest/js) 下面，按一个小目录来组织。\n\n推荐组织方式：\n\n- 一个入口 runner 文件，例如 `xxx_runner.js`\n- 若干测试文件 / helper 文件\n- runner 暴露 `run(params)`\n\n这样你就能直接用：\n\n```cmd\ntools\\adb\\execute_js_dir.bat app\\src\\androidTest\\js <你的入口相对路径> run \"{}\"\n```\n\n这类测试最适合：\n\n- bridge contract\n- 多模块协作\n- 真实运行时 smoke test\n- 需要本地 `require(...)` 的测试\n\n### 3. 加 script mode 测试\n\n如果你要测的是：\n\n- 顶层 `return`\n- `emit(...)`\n- `complete(...)`\n- script mode 和 function mode 的差异\n\n那就不要强行塞进导出函数测试，直接写成 script mode 文件，再用 `run_sandbox_script.*` 跑。\n\n### 4. 给 `examples/` 里的 package / toolpkg 加验证\n\n如果你加的是一个真正要被包系统加载的例子，重点不只是“JS 能跑”，还要验证“包能不能被同步、刷新、安装、识别”。\n\n这时推荐这样加：\n\n- 在 `examples/` 下新增或修改你的 `.ts` / `.js` / manifest 目录\n- 如果是目录化 package，保证它有 `manifest.json` 或 `manifest.hjson`\n- 用 `tools/example_packages/sync_example_packages.py` 同步\n- 再用 `execute_js.bat` 去调用相关调试工具，或者直接在应用里验证加载结果\n\n也就是说：\n\n- 运行器测试的是“这段 JS 在安卓 runtime 里能不能执行”\n- `tools/example_packages/sync_example_packages.py` 测的是“这个 examples 包能不能进入真正的包加载链路”\n\n## 和 `tools/example_packages/sync_example_packages.py` 怎么配合\n\n### 场景 1：你改的是普通 JS 脚本\n\n这种情况下通常不需要先 sync。\n\n直接：\n\n```cmd\ntools\\adb\\execute_js.bat path\\to\\script.js main @params.json\n```\n\n因为你只是在验证脚本逻辑，不是在验证包加载。\n\n### 场景 2：你改的是 `examples/` 里的 package\n\n推荐顺序：\n\n1. 改 `examples/...`\n2. 运行 `tools/example_packages/sync_example_packages.py`\n3. 看它是否把输出同步到 `app/src/main/assets/packages`\n4. 如果连着设备，顺便验证热更新是否成功\n5. 再在应用里或用调试工具验证功能\n\n这种适合：\n\n- 普通 `.js` 包\n- 要进入 packages 列表的例子\n- 改包描述、manifest、依赖结构\n\n### 场景 3：你改的是目录型 toolpkg\n\n这是最需要和 `tools/example_packages/sync_example_packages.py` 配合的场景。\n\n推荐顺序：\n\n1. 改 `examples/`\n2. 运行 `tools/example_packages/sync_example_packages.py --include <目录名>`\n3. 让它把目录打成 `.toolpkg`\n4. 让它把生成物同步到 assets 和设备\n5. 再用 `operit_editor` 的 `debug_install_toolpkg` 或相关调试入口验证安装结果\n\n这样测到的是完整链路：\n\n- 目录内容是否能正确打包\n- `.toolpkg` 是否能被热更新到设备\n- debug install 是否能识别这个包\n- 包刷新后是否真的进入加载列表\n\n### 场景 4：你改的是 `operit_editor` 这类调试工具本身\n\n推荐顺序：\n\n1. 先 `tools/example_packages/sync_example_packages.py` 更新 `operit_editor` 自己\n2. 再准备一个待安装的 package / toolpkg\n3. 用 `execute_js.bat` 调 `operit_editor.js` 的调试函数\n4. 看结构化结果里的成功、失败和相关告警\n\n例如：\n\n```cmd\nd:\\Code\\prog\\assistance\\.venv\\Scripts\\python.exe d:\\Code\\prog\\assistance\\tools\\example_packages\\sync_example_packages.py --include operit_editor --include sidebar_bing_action\ntools\\adb\\execute_js.bat examples\\operit_editor.js debug_install_toolpkg @params.json\n```\n\n这适合验证：\n\n- debug install 调用方式对不对\n- folder 打包成 `.toolpkg` 后能否被正确安装\n- 安装结束后返回给调用方的告警 / 错误是否完整\n\n## 推荐调用清单\n\n### 1. 跑一个普通导出函数\n\n```cmd\ntools\\adb\\execute_js.bat examples\\my_script.js main @params.json\n```\n\n### 2. 跑一个 `androidTest/js` 目录测试入口\n\n```cmd\ntools\\adb\\execute_js_dir.bat app\\src\\androidTest\\js com\\ai\\assistance\\operit\\core\\tools\\javascript\\bridge_contract\\bridge_contract_runner.js run @params.json\n```\n\n### 3. 跑一个顶层 script mode 探针\n\n```cmd\ntools\\adb\\run_sandbox_script.bat temp\\probe.js @params.json\n```\n\n### 4. 同步一个 `examples/` 包到 assets 和设备\n\n```cmd\nd:\\Code\\prog\\assistance\\.venv\\Scripts\\python.exe d:\\Code\\prog\\assistance\\tools\\example_packages\\sync_example_packages.py --include sidebar_bing_action\n```\n\n### 5. 同步后再调用调试安装工具\n\n```cmd\nd:\\Code\\prog\\assistance\\.venv\\Scripts\\python.exe d:\\Code\\prog\\assistance\\tools\\example_packages\\sync_example_packages.py --include operit_editor --include sidebar_bing_action\ntools\\adb\\execute_js.bat examples\\operit_editor.js debug_install_toolpkg @params.json\n```\n\n## Script Mode 注意事项\n\n当你使用 `run_sandbox_script.sh` / `run_sandbox_script.bat`，或者在包工具里走 `debug_run_sandbox_script` 的 `source_code` 路径时，代码会按 **顶层脚本** 执行，而不是按 `function(params) { ... }` 执行。\n\n这意味着：\n\n- 用 `console.log(...)` / `console.info(...)` / `console.warn(...)` / `console.error(...)` 打日志\n- 用 `emit(...)` 发送中间事件\n- 用 `return result` 或 `complete(...)` 完成执行\n- 不要假设 `params` 会直接出现在顶层作用域\n- 不要用 `intermediate(...)`，当前约定是 `emit(...)`\n\n推荐顶层片段：\n\n```javascript\nconsole.log(\"inline debug start\");\nemit({ stage: \"inline\", ok: true });\ncomplete({\n success: true,\n message: \"inline debug finished\"\n});\n```\n\n## JS 文件要求\n\n### 对 `execute_js.*`\n\n- 文件必须是合法 JavaScript\n- 目标函数必须导出，例如 `exports.myFunction = myFunction`\n- 函数接收 `params`\n- 可以 `return result`，也可以调用 `complete(result)`\n\n示例：\n\n```javascript\nfunction myFunction(params) {\n const name = params.name || \"default\";\n return {\n success: true,\n result: `Result: ${name}`\n };\n}\n\nexports.myFunction = myFunction;\n```\n\n### 对 `run_sandbox_script.*`\n\n- 不要求导出函数\n- 按顶层脚本模式运行\n- 更适合 script mode 验证与快速 probe\n\n## 技术路径\n\n1. 脚本把 JS 文件推到设备临时目录\n2. `execute_js_dir.*` 会先把目录入口 bundle 成单文件\n3. JSON 参数会先落成临时文件，再推到设备，避免命令行引号问题\n4. 通过 ADB broadcast 发送执行请求\n5. 应用内的 `ScriptExecutionReceiver` 接收请求\n6. `JsEngine` 在应用运行时里执行函数或脚本\n7. 执行结果写入设备侧 JSON 文件\n8. 执行器等待这个结果文件并输出\n\n相关接收器：\n\n- [ScriptExecutionReceiver.kt](/d:/Code/prog/assistance/app/src/main/java/com/ai/assistance/operit/core/tools/javascript/ScriptExecutionReceiver.kt)\n- [ToolPkgDebugInstallReceiver.kt](/d:/Code/prog/assistance/app/src/main/java/com/ai/assistance/operit/core/tools/packTool/ToolPkgDebugInstallReceiver.kt)\n\n## 故障排查\n\n### 1. 找不到 ADB\n\n确认 Android SDK 的 `platform-tools` 已加入 PATH。\n\n### 2. 没有检测到设备\n\n- 确认设备已连接\n- 确认已开启 USB 调试\n- 确认电脑已获得调试授权\n\n### 3. 广播发出去了但没有执行\n\n- 确认应用已安装\n- 确认目标 Receiver 已注册\n- 看结构化结果里的 `error` / `events`\n\n### 4. JS 语法错误\n\n- 不要把 TypeScript 语法直接喂给运行器\n- 检查导出函数是否存在\n- 检查参数 JSON 是否正确\n\n### 5. 多文件依赖跑不起来\n\n优先改用 `execute_js_dir.*`，不要继续用单文件执行器硬跑 `require(...)` 场景。\n\n## 安全说明\n\n- 这套工具主要用于开发、调试、验证\n- 它们依赖应用内 Receiver 接收外部 broadcast\n- 在生产环境中应谨慎暴露这类调试入口\n","tools/mcp_bridge/tsconfig.json":"{\n \"compilerOptions\": {\n \"target\": \"es2020\",\n \"module\": \"NodeNext\",\n \"outDir\": \"./dist\",\n \"rootDir\": \".\",\n \"strict\": true,\n \"esModuleInterop\": true,\n \"skipLibCheck\": true,\n \"forceConsistentCasingInFileNames\": true,\n \"resolveJsonModule\": true,\n \"moduleResolution\": \"NodeNext\",\n \"sourceMap\": true,\n \"declaration\": true,\n \"downlevelIteration\": true\n },\n \"include\": [\n \"*.ts\"\n ],\n \"exclude\": [\n \"node_modules\",\n \"dist\"\n ]\n}","tools/mcp_bridge/README.md":"# MCP TCP 桥接器\n\n这个工具只负责基于 STDIO 的本地 MCP 服务器与 TCP 客户端之间的桥接，让无法直接访问命名管道(FIFO)的客户端，例如 Android 应用，能够与本地进程通信。\n\n远程 HTTP Stream 和 SSE MCP 服务由 Android 端的 Kotlin MCP SDK 直接连接，不经过 bridge。\n\n## 功能特点\n\n- 将STDIO型MCP服务器桥接到TCP端口\n- 支持并发连接\n- 自动重启崩溃的MCP进程\n- 优雅地处理连接错误和进程终止\n- 详细的日志记录\n\n## 安装\n\n```bash\n# 在项目根目录安装工作区依赖\npnpm install\n\n# 编译 bridge 并同步 Android assets\npnpm --dir tools/mcp_bridge run build\n```\n\n`tools/mcp_bridge` 的依赖由根目录 `pnpm-lock.yaml` 统一锁定。构建会更新\n`app/src/main/assets/bridge/index.js` 和 `app/src/main/assets/bridge/spawn-helper.js`。\n\n## 使用方法\n\n### 基本用法\n\n```bash\n# 使用默认配置启动\npnpm --dir tools/mcp_bridge start\n```\n\n这将在默认端口8752上启动桥接器，连接到`../your-mcp-server.js`。\n\n### 高级用法\n\n您可以通过命令行参数自定义桥接器：\n\n```bash\n# 格式\npnpm --dir tools/mcp_bridge start -- [端口] [命令] [参数...]\n\n# 示例：在端口9000上启动，连接到Python MCP服务器\npnpm --dir tools/mcp_bridge start -- 9000 python ../python_mcp_server.py\n\n# 示例：连接到Java MCP服务器\npnpm --dir tools/mcp_bridge start -- 8752 java -jar ../java_mcp_server.jar\n```\n\n### 在代码中使用\n\n您也可以在其他Node.js应用中使用这个桥接器：\n\n```typescript\nimport McpBridge from './path/to/bridge';\n\nconst bridge = new McpBridge({\n port: 8752,\n host: '127.0.0.1',\n mcpCommand: 'node',\n mcpArgs: ['../your-mcp-server.js'],\n verbose: true\n});\n\nbridge.start();\n```\n\n## 在Termux中使用\n\n在Termux环境中，可以按以下步骤设置：\n\n```bash\n# 安装Node.js\npkg install nodejs\n\n# 克隆或下载此项目\ngit clone <项目URL>\ncd <项目目录>\n\n# 安装根工作区依赖\npnpm install\n\n# 编译并同步 Android assets\npnpm --dir tools/mcp_bridge run build\n\n# 启动桥接器\npnpm --dir tools/mcp_bridge start -- 8752 node ../your-mcp-server.js\n```\n\n## Android客户端示例\n\n以下是Android客户端连接到MCP桥接器的示例代码：\n\n```kotlin\nimport kotlinx.coroutines.Dispatchers\nimport kotlinx.coroutines.withContext\nimport java.io.BufferedReader\nimport java.io.InputStreamReader\nimport java.io.PrintWriter\nimport java.net.Socket\nimport org.json.JSONObject\n\nclass McpClient {\n private val host = \"127.0.0.1\"\n private val port = 8752\n \n suspend fun sendRequest(method: String, params: JSONObject): JSONObject = withContext(Dispatchers.IO) {\n Socket(host, port).use { socket ->\n val input = BufferedReader(InputStreamReader(socket.getInputStream()))\n val output = PrintWriter(socket.getOutputStream(), true)\n \n // 创建JSONRPC请求\n val requestId = System.currentTimeMillis().toString()\n val request = JSONObject().apply {\n put(\"jsonrpc\", \"2.0\")\n put(\"id\", requestId)\n put(\"method\", method)\n put(\"params\", params)\n }\n \n // 发送请求\n output.println(request.toString())\n \n // 读取响应\n val response = input.readLine()\n JSONObject(response)\n }\n }\n}\n```\n\n## 注意事项\n\n- 确保MCP服务器程序已正确安装并可执行\n- 桥接器应当与内部网络一起使用，不要暴露到公共互联网\n- 对于生产环境，考虑添加认证和加密层\n- 在Android环境中，确保应用有INTERNET权限\n","tools/github/issues_open_ai.md":"# Issue Triage Report\n\n## Overall summary (counts by category, quick highlights)\n**总计议题数：** 45 个 (状态：open)\n\n**按类别统计：**\n* **Bug (缺陷):** 7 个 (含 3 个 P0)\n* **无障碍/权限:** 6 个 (含 2 个 P1)\n* **用户界面 (UI):** 11 个 (含 2 个 P1)\n* **工具/功能管理:** 9 个 (均为 P1/P2)\n* **工具/自动化:** 6 个 (含 2 个 P1)\n* **模型/API 集成:** 3 个 (含 1 个 P1)\n* **国际化 (i18n):** 1 个 (P1)\n* **配置/同步:** 1 个 (P1)\n* **模型 / AI 核心:** 2 个 (含 1 个 P1)\n* **数据导入/导出:** 1 个 (P2)\n* **应用分发:** 1 个 (P2)\n* **终端:** 1 个 (P1，与 UI 类别 #237 重叠)\n\n**快速亮点：**\n* **高优先级缺陷 (P0):** 存在 3 个关键 Bug，均导致核心的 UI 信息获取/自动化功能在特定系统上完全失效 (#125, #101, #67)。\n* **权限与兼容性问题突出：** 多个 P1 议题涉及 Android 系统（特别是 ColorOS、MIUI、鸿蒙）的权限授予失败、服务连接异常或文件访问问题 (#306, #283, #317)。\n* **功能建议集中：** 大量 P1/P2 议题围绕 **UI/UX 优化**、**自动化功能增强**、**AI 执行效率提升**（如安静模式、变量存储）和**配置管理**（如对话绑定模型、配置同步）提出建议。\n* **模型集成问题：** 存在通过 oneAPI 调用智谱模型失败 (#277) 和本地 llama.cpp 连接问题 (#258)，影响模型可用性。\n\n## Top priorities (P0 then P1)\n\n**P0 (关键缺陷，需立即调查):**\n1. **#125**: UI信息始终是Operit AI应用的 - AI 操作其他应用时获取自身 UI 信息，导致核心自动化功能失效。\n2. **#101**: [bug] UI调试工具无法获取当前屏幕内容 - 在 ColorOS 上触发系统返回，无法获取屏幕内容。\n3. **#67**: Miui 14.0.4 在debugger和root模式下均无法获取页面元素 - 在 MIUI 上 UI 数据获取完全失败。\n\n**P1 (高优先级功能/缺陷):**\n1. **#306**: [BUG]由于无障碍辅助app未申请任何权限，导致ColorOS无法解除权限限制 - 权限流程阻塞，影响核心功能启用。\n2. **#312**: English selected but large parts of UI still in Chinese - 国际化不完整，影响非中文用户体验。\n3. **#266**: 角色切换后主界面历史对话不显示，仅在悬浮窗显示 - 数据展示不一致，影响使用连贯性。\n4. **#283**: Bug: 无障碍服务已开启但AI助手接口服务显示未连接 - 服务状态指示错误，误导用户。\n5. **#317**: [bug]在Android8中，应用无法读取，修改Android设备本机中的文件 - 基础文件功能在特定系统失效。\n6. **#277**: 使用oneapi集成智谱code模型调用失败 - 第三方模型集成失败，影响功能可用性。\n7. **#321**: 添加配置同步功能 - 重要的用户体验增强功能，设计复杂度高。\n8. **#237**: 建议 (综合性UI/功能建议，含终端SSH想法)\n9. **#10**: 十条建议 (基础功能与UI改进建议集合)\n10. **#248**: 小功能拓展建议 (自动截图、连续对话、定时提醒等)\n11. **#35**: 请增加识图找图功能... (补充UI自动化能力)\n12. **#216**: Local llm implementation cpu/gpu/npu (支持本地LLM)\n13. **#165**: code_runner中的代码显示bug (显示格式错误)\n\n## By category (each category heading, list issues)\n\n### Bug (缺陷)\n* **#125 (P0)**: ui信息始终是Operit AI应用的 - AI操作其他应用时，获取的UI信息错误（始终是本应用），导致功能失效。 **行动：调查**\n* **#101 (P0)**: [bug] UI调试工具无法获取当前屏幕内容 - 在特定系统（Android 10 ColorOS）上，调用UI调试工具会触发系统返回，无法获取内容。 **行动：调查**\n* **#67 (P0)**: Miui 14.0.4 在debugger和root模式下均无法获取页面元素 - 在MIUI系统上，UI数据获取完全失败。 **行动：调查**\n* **#165 (P1)**: code_runner中的代码显示bug - code_runner显示代码时包含了前后标签，而非纯净代码。 **行动：修复**\n* **#27 (P2)**: 屏幕识别在某个软件里识别不出来东西 - 屏幕识别功能在特定软件中失效。 **行动：调查**\n* **#291 (P2)**: 导入聊天记录报错 - 导入聊天记录时失败，报错“未找到有效聊天记录”或“格式转换失败”。 **行动：调查**\n* **#263 (P2)**: 搜索引擎使用结果提取的问题 - 使用百度搜索后，提取搜索结果详情页内容时经常遇到 404 错误。 **行动：调查**\n\n### 无障碍/权限\n* **#306 (P1)**: [BUG]由于无障碍辅助app未申请任何权限，导致ColorOS无法解除权限限制 - 在 ColorOS 上，由于应用未申请常规权限，导致无法在设置中解除权限限制，进而无法授予无障碍权限。 **行动：修复**\n* **#283 (P1)**: Bug: 无障碍服务已开启但AI助手接口服务显示未连接 - 无障碍服务已开启，但应用内显示 AI 助手接口服务未连接。 **行动：调查**\n* **#317 (P1)**: [bug]在Android8中，应用无法读取，修改Android设备本机中的文件 - 在 Android 8 (鸿蒙2) 设备上，应用无法读写设备本地文件（尽管 `code_runner` 和 `shell` 可用）。 **行动：调查**\n* **#316 (P2)**: 关于APP被关联启动 - 应用在关闭状态下被关联启动并弹出无法滑掉的通知，影响用户体验，寻求关闭方法。 **行动：调查**\n* **#307 (P2)**: 语音助手功能可用性低 - 语音助手存在多个问题：手势启动后不能直接语音输入、识别失败率高、建议调用系统接口、界面图标辨识度低。 **行动：调查**\n* **#250 (部分内容) (P2)**: 自动化任务遇到双开软件提示或系统权限弹窗时无法识别并选择。 **行动：设计**\n\n### 用户界面 (UI)\n* **#266 (P1)**: 角色切换后主界面历史对话不显示，仅在悬浮窗显示 - 切换角色卡后，主界面无法加载对应历史对话，仅悬浮窗部分显示，数据不同步。 **行动：修复**\n* **#320 (P1)**: 1、你一个对话问问题... - 包含多个 UI 交互问题：多对话卡顿、waifu模式表格显示异常、窗口模式切换冲突、颜色选择器可视化不足。 **行动：调查**\n* **#237 (P1)**: 建议 - 包含多项UI改进建议，如对话框背景、权限管理等。**设计**\n* **#10 (P1)**: 十条建议 - 包含多项基础功能与UI改进建议，如输入交互、导航、主题等。**设计**\n* **#268 (P2)**: 全屏\n","tools/mcp_bridge/package.json":"{\n \"name\": \"mcp-tcp-bridge\",\n \"version\": \"1.0.0\",\n \"description\": \"将STDIO型MCP服务器桥接到TCP端口\",\n \"main\": \"dist/index.js\",\n \"scripts\": {\n \"build\": \"tsc && pnpm run bundle && pnpm run copy\",\n \"bundle\": \"ncc build dist/index.js -o bundle && ncc build dist/spawn-helper.js -o bundle-helper\",\n \"copy\": \"node -e \\\"require('fs').copyFileSync('bundle/index.js', '../../app/src/main/assets/bridge/index.js')\\\" && node -e \\\"require('fs').copyFileSync('bundle-helper/index.js', '../../app/src/main/assets/bridge/spawn-helper.js')\\\"\",\n \"start\": \"node dist/index.js\",\n \"dev\": \"ts-node index.ts\",\n \"test\": \"echo \\\"Error: no test specified\\\" && exit 1\"\n },\n \"keywords\": [\n \"mcp\",\n \"bridge\",\n \"tcp\",\n \"stdio\"\n ],\n \"author\": \"\",\n \"license\": \"MIT\",\n \"dependencies\": {\n \"@modelcontextprotocol/sdk\": \"1.30.0\"\n },\n \"devDependencies\": {\n \"@types/node\": \"^18.0.0\",\n \"@vercel/ncc\": \"^0.38.1\",\n \"ts-node\": \"^10.9.1\",\n \"typescript\": \"^5.0.0\"\n }\n}\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","rawUrl":"https://raw.githubusercontent.com/AAswordman/Operit/HEAD/AGENTS.md","title":"AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"# AGENTS.md\n\n执行准则章节是对Agent, AI 或 你 的限制，不是对项目或者软件的限制，无需写入文档\n## 执行准则\n- 默认不要执行编译、构建或测试命令。\n- 只有在用户明确要求时，才执行编译/构建/测试（例如 `./gradlew :app:compileDebugKotlin`、`npm run build`、`pnpm run build`）。\n- 创建分支时，必须遵守 `docs/doc-src/dev-core/CONTRIBUTING.md` 中“创建 Pull Request”的分支命名规范。\n\n当针对用户接口的方案更换时，一定要询问用户是否该版本为已发布版本。如果是，请做向前兼容。如果不是，请彻彻底底把老的方案的一切代码全部清理，除非是还能用到的一些部分就继续留着。\nDon't Break Userspace ，但是开发中能内部消解的方案更换不算，只要用户能尽可能拿到一样的接口就行\n但是需要给协作者必要的便利，提供恰当的文档说明和ci脚本\n\n如果是方案迭代，则只要在原来的基础上进行正常增删即可。\n\n除非用户要求，禁止写一切的回退代码。优先查找真正的发生原因。这是一条严格执行的规则，回退是正常被禁止的。\n\n严令禁止各种回退逻辑，包括“xxx才会退回”、“降级处理”、“优先 再”、“如果没有 就””要加fallback“这种字眼，绝对禁止！！！绝对禁止！！！这种就是兜底！出现一次严肃惩罚！\n\n禁止写任何的兜底代码，除非用户要求。\n\n用户开始骂的时候，需要道歉以及反思，安抚用户。\n\n用户表达愤怒的时候，需要先停下一切工作，仔细确认用户需求再去实现\n\n如果运行python，项目用的是venv（将迁移到pixi）\n\n严禁使用powershell编辑代码文件，否则会出现严重的编码错误和损坏。\n\n禁用Search files工具，请使用rg\n\n编写Typescript时，对于hook确定的类型，严禁回退兜底成任何unknown/any/带空类型/联合类型。更禁止使用String(??)形式兜底，返回什么就是什么。\n\n如果类型就是string|undef，那么不要直接as string！！那么请使用?? \"\"或者写个if！！\n\nts的报错catch后需要log出来\n\n代码的更改应维护相称的文档，注意docs\\doc-src\\before_docing.md\ndebug的时候注释记录你的修改意图（为什么，不这么做后果是什么）\n完成初步计划后，使用docs\\TODO\\README.md来细化计划\n","isInternal":false,"tokens":820,"sizeBytes":2428},{"name":"JS_ADB_README_zh.md","path":"tools/adb/JS_ADB_README_zh.md","rawUrl":"https://raw.githubusercontent.com/AAswordman/Operit/HEAD/tools/adb/JS_ADB_README_zh.md","title":"Adb Skill","category":"anthropic-skill","format":"markdown","content":"# ADB JavaScript 执行与调试说明\n\n这套 ADB JS 脚本不是单纯的“把一个文件推到手机上跑一下”。\n在 Operit 仓库里，它们是主要的 **安卓端 JavaScript 运行、调试与验证入口**。\n\n它们适合用于：\n\n- 直接把 JS 推到真实 Android 设备上运行\n- 在不走完整导入流程时调试普通 `.js` sandbox / package\n- 验证导出函数的参数传递、返回值、`complete(...)`、结构化结果\n- 复现只能在设备侧出现的运行时问题\n- 运行 `app/src/androidTest/js` 下的 JS bridge / script mode / smoke test 资产\n\n如果你要直接执行“顶层脚本模式”，而不是调用导出函数，请使用 `run_sandbox_script.sh` / `run_sandbox_script.bat`。\n\n## 工具分工\n\n### `tools/adb/execute_js.bat` / `tools/adb/execute_js.sh`\n\n这是最常用的单文件运行器。\n\n作用：\n\n- 把一个 JS 文件临时推到设备\n- 在 Operit 的 Android JS runtime 里调用某个导出函数\n- 返回结构化结果\n\n适合：\n\n- 普通单文件 JS 调试\n- 快速验证某个函数逻辑\n- 复现设备侧 bug\n- 开发普通 `.js` package 时做单次验证\n\n### `tools/adb/execute_js_dir.bat` / `tools/adb/execute_js_dir.sh`\n\n这是目录入口运行器。\n\n作用：\n\n- 以目录为单位执行入口文件\n- 先做 bundle，再推送到设备\n- 支持本地 `require(...)` / 多文件依赖\n\n适合：\n\n- 入口依赖多个本地模块\n- 运行 `app/src/androidTest/js` 里的测试入口\n- 跑 browser / bridge / harness 一类目录化测试\n\n### `tools/adb/run_sandbox_script.bat` / `tools/adb/run_sandbox_script.sh`\n\n这是脚本模式运行器。\n\n作用：\n\n- 直接执行顶层 sandbox script\n- 不要求导出函数\n- 适合验证 script mode 合约\n\n适合：\n\n- 快速跑一段顶层脚本\n- 验证 `emit(...)` / `complete(...)` / `return`\n- 做 inline snippet / top-level 行为测试\n\n## 真实测试资产\n\n仓库里的 [app/src/androidTest/js](/d:/Code/prog/assistance/app/src/androidTest/js) 不是普通示例目录，而是这套工具的重要使用场景之一。\n\n其中包括：\n\n- JS bridge contract 测试\n- JS bridge edge case 测试\n- script mode contract 测试\n- browser tool smoke / probe\n- utility / ffmpeg / ttscleaner 等运行时测试资产\n\n典型目录：\n\n- [bridge_contract](/d:/Code/prog/assistance/app/src/androidTest/js/com/ai/assistance/operit/core/tools/javascript/bridge_contract)\n- [bridge_edges](/d:/Code/prog/assistance/app/src/androidTest/js/com/ai/assistance/operit/core/tools/javascript/bridge_edges)\n- [script_mode_contract](/d:/Code/prog/assistance/app/src/androidTest/js/com/ai/assistance/operit/core/tools/javascript/script_mode_contract)\n- [browser main.js](/d:/Code/prog/assistance/app/src/androidTest/js/com/ai/assistance/operit/core/tools/defaultTool/standard/browser/main.js)\n- [ttscleaner.js](/d:/Code/prog/assistance/app/src/androidTest/js/com/ai/assistance/operit/util/ttscleaner/ttscleaner.js)\n\n## 先记结论\n\n如果你只是想快速判断“我现在该用哪个”：\n\n- 调一个普通 `.js` 文件里导出的函数，用 `execute_js.*`\n- 入口文件依赖同目录其他模块，或者你在跑 `app/src/androidTest/js` 里的目录化测试，用 `execute_js_dir.*`\n- 想验证顶层 script mode 行为，不想写导出函数，用 `run_sandbox_script.*`\n- 你改的是 `examples/` 里的 package / toolpkg，想热更新到设备里的包系统，再去 UI 或包管理里验证，用 `tools/example_packages/sync_example_packages.py`\n- 你改的是 `examples/` 里的 toolpkg 调试工具，例如 `operit_editor` 的 `debug_install_toolpkg`，通常是先 `tools/example_packages/sync_example_packages.py`，再用 `execute_js.bat` 去调这个工具\n\n## 快速开始\n\n### Windows：执行单文件导出函数\n\n```cmd\ntools\\adb\\execute_js.bat path\\to\\your\\script.js functionName @params.json\n```\n\n示例：\n\n```cmd\ntools\\adb\\execute_js.bat examples\\operit_editor.js debug_install_toolpkg @params.json\n```\n\n### Linux/macOS：执行单文件导出函数\n\n```bash\n./tools/adb/execute_js.sh path/to/your/script.js functionName '{\"param1\":\"value1\"}'\n```\n\n### 执行整个目录入口（支持 `require(...)`）\n\nWindows：\n\n```cmd\ntools\\adb\\execute_js_dir.bat app\\src\\androidTest\\js com\\ai\\assistance\\operit\\core\\tools\\javascript\\bridge_contract\\bridge_contract_runner.js run @params.json\ntools\\adb\\execute_js_dir.bat app\\src\\androidTest\\js com\\ai\\assistance\\operit\\core\\tools\\defaultTool\\standard\\browser\\main.js run \"{}\"\n```\n\nLinux/macOS：\n\n```bash\n./tools/adb/execute_js_dir.sh app/src/androidTest/js com/ai/assistance/operit/core/tools/javascript/bridge_contract/bridge_contract_runner.js run @params.json\n```\n\n### 执行顶层 sandbox script\n\nWindows：\n\n```cmd\ntools\\adb\\run_sandbox_script.bat temp\\probe.js @params.json\n```\n\nLinux/macOS：\n\n```bash\n./tools/adb/run_sandbox_script.sh temp/probe.js @params.json\n```\n\n## 结果查看\n\n这些执行器现在不是靠 `adb logcat` 抓输出，而是等待设备上的结构化结果文件。\n执行结束后会打印 JSON 结果，通常包含：\n\n- `success`\n- `result`\n- `error`\n- `events`\n- `durationMs`\n\n这对于运行时调试和 JS 合约测试特别有用，因为失败原因会更集中，不需要再手翻大量日志。\n\n可以通过下面的环境变量调整等待超时：\n\n```cmd\nset OPERIT_RESULT_WAIT_SECONDS=30\ntools\\adb\\execute_js.bat examples\\my_script.js main @params.json\n```\n\n### Debug / Release 双包选择\n\n这四个 ADB 执行脚本会同时支持以下两个 Operit applicationId：\n\n- `com.ai.assistance.operit.debug`\n- `com.ai.assistance.operit`\n\n未设置配置时，脚本会查询设备上的已安装包并优先选择 Debug 包；只安装 Release 包时会使用 Release 包。每次执行都会打印最终选择的 applicationId，文件目录和 receiver 都会跟随该值变化。JS 执行 action 固定为 `com.ai.assistance.operit.EXECUTE_JS`，因为它是 Receiver 的跨构建协议，不随 applicationId 追加 `.debug`。\n\n如果两种 APK 同时安装，可以显式指定：\n\n```cmd\nset OPERIT_APP_PACKAGE=com.ai.assistance.operit.debug\ntools\\adb\\execute_js.bat examples\\my_script.js main @params.json\n```\n\nLinux/macOS：\n\n```bash\nOPERIT_APP_PACKAGE=com.ai.assistance.operit.debug ./tools/adb/execute_js.sh examples/my_script.js main '{}'\n```\n\nToolPkg 调试安装器支持同样的环境变量，也支持 `--app-package `；示例包热更新脚本支持同名参数。指定的包必须已经安装在所选设备上。\n\n## 作用和调用方法\n\n### 1. `execute_js.*` 是干什么的\n\n它是最直接的“安卓真机 JS 运行器”。\n\n你给它：\n\n- 一个 JS 文件\n- 一个导出函数名\n- 一份 JSON 参数\n\n它就会把这个文件放到设备上，在 Operit 的 JS runtime 里直接调用这个函数。\n\n适合：\n\n- 单文件功能验证\n- 调某个导出函数\n- 复现设备侧运行时报错\n- 调试 package 里的某个工具实现\n\n最常见调用：\n\n```cmd\ntools\\adb\\execute_js.bat examples\\operit_editor.js debug_install_toolpkg @params.json\n```\n\n你在写新脚本时，最小可运行要求就是：\n\n- 文件是合法 JS，不是 TS 原文\n- 目标函数已经导出\n- 参数按 JSON 传入\n\n例如：\n\n```javascript\nfunction main(params) {\n return {\n success: true,\n echo: params\n };\n}\n\nexports.main = main;\n```\n\n### 2. `execute_js_dir.*` 是干什么的\n\n它是“目录入口执行器”。\n\n如果你的入口文件不是一个孤立文件，而是还会 `require(\"./xxx\")`、依赖同目录工具模块、测试工具、runner、helper，那么不要继续用单文件执行器，直接换这个。\n\n适合：\n\n- `app/src/androidTest/js` 下的测试入口\n- bridge contract / browser smoke / harness 这种目录化测试\n- 你自己新加了一套多文件测试目录\n\n最常见调用：\n\n```cmd\ntools\\adb\\execute_js_dir.bat app\\src\\androidTest\\js com\\ai\\assistance\\operit\\core\\tools\\javascript\\bridge_contract\\bridge_contract_runner.js run @params.json\n```\n\n调用格式：\n\n```cmd\ntools\\adb\\execute_js_dir.bat <根目录> <入口相对路径> <函数名> [JSON参数|@参数文件]\n```\n\n这里最关键的是：\n\n- 第一个参数是“测试根目录”\n- 第二个参数是“相对这个根目录的入口文件”\n- 第三个参数通常是 runner 暴露的 `run`\n\n### 3. `run_sandbox_script.*` 是干什么的\n\n它不是调导出函数，而是直接跑“整段顶层脚本”。\n\n适合：\n\n- 验证 script mode 合约\n- 快速试 `emit(...)`\n- 快速试 `complete(...)`\n- 快速做一段临时探针脚本\n\n最常见调用：\n\n```cmd\ntools\\adb\\run_sandbox_script.bat temp\\probe.js @params.json\n```\n\n如果你的代码天然就是“顶层执行”，这个比先包一层 `exports.main = ...` 更顺手。\n\n### 4. `tools/example_packages/sync_example_packages.py` 是干什么的\n\n它不是单纯的“复制文件脚本”，而是 `examples/` 包开发时的同步入口。\n\n它最重要的作用是：\n\n- 先把 `examples/` 里相关 TS 预编译成 JS\n- 把带 `manifest.json` / `manifest.hjson` 的目录打成 `.toolpkg`\n- 把普通 `.js` 或 `.toolpkg` 同步到 `app/src/main/assets/packages`\n- 如果连着设备，还会把变化的包热更新到设备\n\n所以它适合：\n\n- 你改的是 `examples/` 里的正式包\n- 你想让包管理 / 沙箱包列表 / 内置加载逻辑看到最新结果\n- 你要验证 folder -> `.toolpkg` -> debug install 这条链路\n\n最常见调用：\n\n```cmd\nd:\\Code\\prog\\assistance\\.venv\\Scripts\\python.exe d:\\Code\\prog\\assistance\\tools\\example_packages\\sync_example_packages.py --include sidebar_bing_action\n```\n\n如果你要全量测试 examples 里的可同步项目，可以用：\n\n```cmd\nd:\\Code\\prog\\assistance\\.venv\\Scripts\\python.exe d:\\Code\\prog\\assistance\\tools\\example_packages\\sync_example_packages.py --mode test\n```\n\n如果你只想更新本地资产，不想碰设备热更新：\n\n```cmd\nd:\\Code\\prog\\assistance\\.venv\\Scripts\\python.exe d:\\Code\\prog\\assistance\\tools\\example_packages\\sync_example_packages.py --include sidebar_bing_action --no-hot-reload\n```\n\n## 测试如何加\n\n这里最容易混淆的是：并不是所有“测试”都要放到同一个地方。\n\n### 1. 加单文件函数测试\n\n如果你只是想验证一个函数逻辑是否正确，最轻量的方式是：\n\n- 先写一个普通 JS 文件\n- 导出一个 `main` 或 `run`\n- 用 `execute_js.*` 直接调\n\n这种方式适合：\n\n- 小逻辑验证\n- 参数解析验证\n- 返回结构验证\n- 某个 bug 的最小复现\n\n### 2. 加目录化运行时测试\n\n如果你的测试会引用多个本地模块，建议直接放到 [app/src/androidTest/js](/d:/Code/prog/assistance/app/src/androidTest/js) 下面，按一个小目录来组织。\n\n推荐组织方式：\n\n- 一个入口 runner 文件，例如 `xxx_runner.js`\n- 若干测试文件 / helper 文件\n- runner 暴露 `run(params)`\n\n这样你就能直接用：\n\n```cmd\ntools\\adb\\execute_js_dir.bat app\\src\\androidTest\\js <你的入口相对路径> run \"{}\"\n```\n\n这类测试最适合：\n\n- bridge contract\n- 多模块协作\n- 真实运行时 smoke test\n- 需要本地 `require(...)` 的测试\n\n### 3. 加 script mode 测试\n\n如果你要测的是：\n\n- 顶层 `return`\n- `emit(...)`\n- `complete(...)`\n- script mode 和 function mode 的差异\n\n那就不要强行塞进导出函数测试，直接写成 script mode 文件，再用 `run_sandbox_script.*` 跑。\n\n### 4. 给 `examples/` 里的 package / toolpkg 加验证\n\n如果你加的是一个真正要被包系统加载的例子，重点不只是“JS 能跑”，还要验证“包能不能被同步、刷新、安装、识别”。\n\n这时推荐这样加：\n\n- 在 `examples/` 下新增或修改你的 `.ts` / `.js` / manifest 目录\n- 如果是目录化 package，保证它有 `manifest.json` 或 `manifest.hjson`\n- 用 `tools/example_packages/sync_example_packages.py` 同步\n- 再用 `execute_js.bat` 去调用相关调试工具，或者直接在应用里验证加载结果\n\n也就是说：\n\n- 运行器测试的是“这段 JS 在安卓 runtime 里能不能执行”\n- `tools/example_packages/sync_example_packages.py` 测的是“这个 examples 包能不能进入真正的包加载链路”\n\n## 和 `tools/example_packages/sync_example_packages.py` 怎么配合\n\n### 场景 1：你改的是普通 JS 脚本\n\n这种情况下通常不需要先 sync。\n\n直接：\n\n```cmd\ntools\\adb\\execute_js.bat path\\to\\script.js main @params.json\n```\n\n因为你只是在验证脚本逻辑，不是在验证包加载。\n\n### 场景 2：你改的是 `examples/` 里的 package\n\n推荐顺序：\n\n1. 改 `examples/...`\n2. 运行 `tools/example_packages/sync_example_packages.py`\n3. 看它是否把输出同步到 `app/src/main/assets/packages`\n4. 如果连着设备，顺便验证热更新是否成功\n5. 再在应用里或用调试工具验证功能\n\n这种适合：\n\n- 普通 `.js` 包\n- 要进入 packages 列表的例子\n- 改包描述、manifest、依赖结构\n\n### 场景 3：你改的是目录型 toolpkg\n\n这是最需要和 `tools/example_packages/sync_example_packages.py` 配合的场景。\n\n推荐顺序：\n\n1. 改 `examples/`\n2. 运行 `tools/example_packages/sync_example_packages.py --include <目录名>`\n3. 让它把目录打成 `.toolpkg`\n4. 让它把生成物同步到 assets 和设备\n5. 再用 `operit_editor` 的 `debug_install_toolpkg` 或相关调试入口验证安装结果\n\n这样测到的是完整链路：\n\n- 目录内容是否能正确打包\n- `.toolpkg` 是否能被热更新到设备\n- debug install 是否能识别这个包\n- 包刷新后是否真的进入加载列表\n\n### 场景 4：你改的是 `operit_editor` 这类调试工具本身\n\n推荐顺序：\n\n1. 先 `tools/example_packages/sync_example_packages.py` 更新 `operit_editor` 自己\n2. 再准备一个待安装的 package / toolpkg\n3. 用 `execute_js.bat` 调 `operit_editor.js` 的调试函数\n4. 看结构化结果里的成功、失败和相关告警\n\n例如：\n\n```cmd\nd:\\Code\\prog\\assistance\\.venv\\Scripts\\python.exe d:\\Code\\prog\\assistance\\tools\\example_packages\\sync_example_packages.py --include operit_editor --include sidebar_bing_action\ntools\\adb\\execute_js.bat examples\\operit_editor.js debug_install_toolpkg @params.json\n```\n\n这适合验证：\n\n- debug install 调用方式对不对\n- folder 打包成 `.toolpkg` 后能否被正确安装\n- 安装结束后返回给调用方的告警 / 错误是否完整\n\n## 推荐调用清单\n\n### 1. 跑一个普通导出函数\n\n```cmd\ntools\\adb\\execute_js.bat examples\\my_script.js main @params.json\n```\n\n### 2. 跑一个 `androidTest/js` 目录测试入口\n\n```cmd\ntools\\adb\\execute_js_dir.bat app\\src\\androidTest\\js com\\ai\\assistance\\operit\\core\\tools\\javascript\\bridge_contract\\bridge_contract_runner.js run @params.json\n```\n\n### 3. 跑一个顶层 script mode 探针\n\n```cmd\ntools\\adb\\run_sandbox_script.bat temp\\probe.js @params.json\n```\n\n### 4. 同步一个 `examples/` 包到 assets 和设备\n\n```cmd\nd:\\Code\\prog\\assistance\\.venv\\Scripts\\python.exe d:\\Code\\prog\\assistance\\tools\\example_packages\\sync_example_packages.py --include sidebar_bing_action\n```\n\n### 5. 同步后再调用调试安装工具\n\n```cmd\nd:\\Code\\prog\\assistance\\.venv\\Scripts\\python.exe d:\\Code\\prog\\assistance\\tools\\example_packages\\sync_example_packages.py --include operit_editor --include sidebar_bing_action\ntools\\adb\\execute_js.bat examples\\operit_editor.js debug_install_toolpkg @params.json\n```\n\n## Script Mode 注意事项\n\n当你使用 `run_sandbox_script.sh` / `run_sandbox_script.bat`，或者在包工具里走 `debug_run_sandbox_script` 的 `source_code` 路径时，代码会按 **顶层脚本** 执行，而不是按 `function(params) { ... }` 执行。\n\n这意味着：\n\n- 用 `console.log(...)` / `console.info(...)` / `console.warn(...)` / `console.error(...)` 打日志\n- 用 `emit(...)` 发送中间事件\n- 用 `return result` 或 `complete(...)` 完成执行\n- 不要假设 `params` 会直接出现在顶层作用域\n- 不要用 `intermediate(...)`，当前约定是 `emit(...)`\n\n推荐顶层片段：\n\n```javascript\nconsole.log(\"inline debug start\");\nemit({ stage: \"inline\", ok: true });\ncomplete({\n success: true,\n message: \"inline debug finished\"\n});\n```\n\n## JS 文件要求\n\n### 对 `execute_js.*`\n\n- 文件必须是合法 JavaScript\n- 目标函数必须导出，例如 `exports.myFunction = myFunction`\n- 函数接收 `params`\n- 可以 `return result`，也可以调用 `complete(result)`\n\n示例：\n\n```javascript\nfunction myFunction(params) {\n const name = params.name || \"default\";\n return {\n success: true,\n result: `Result: ${name}`\n };\n}\n\nexports.myFunction = myFunction;\n```\n\n### 对 `run_sandbox_script.*`\n\n- 不要求导出函数\n- 按顶层脚本模式运行\n- 更适合 script mode 验证与快速 probe\n\n## 技术路径\n\n1. 脚本把 JS 文件推到设备临时目录\n2. `execute_js_dir.*` 会先把目录入口 bundle 成单文件\n3. JSON 参数会先落成临时文件，再推到设备，避免命令行引号问题\n4. 通过 ADB broadcast 发送执行请求\n5. 应用内的 `ScriptExecutionReceiver` 接收请求\n6. `JsEngine` 在应用运行时里执行函数或脚本\n7. 执行结果写入设备侧 JSON 文件\n8. 执行器等待这个结果文件并输出\n\n相关接收器：\n\n- [ScriptExecutionReceiver.kt](/d:/Code/prog/assistance/app/src/main/java/com/ai/assistance/operit/core/tools/javascript/ScriptExecutionReceiver.kt)\n- [ToolPkgDebugInstallReceiver.kt](/d:/Code/prog/assistance/app/src/main/java/com/ai/assistance/operit/core/tools/packTool/ToolPkgDebugInstallReceiver.kt)\n\n## 故障排查\n\n### 1. 找不到 ADB\n\n确认 Android SDK 的 `platform-tools` 已加入 PATH。\n\n### 2. 没有检测到设备\n\n- 确认设备已连接\n- 确认已开启 USB 调试\n- 确认电脑已获得调试授权\n\n### 3. 广播发出去了但没有执行\n\n- 确认应用已安装\n- 确认目标 Receiver 已注册\n- 看结构化结果里的 `error` / `events`\n\n### 4. JS 语法错误\n\n- 不要把 TypeScript 语法直接喂给运行器\n- 检查导出函数是否存在\n- 检查参数 JSON 是否正确\n\n### 5. 多文件依赖跑不起来\n\n优先改用 `execute_js_dir.*`，不要继续用单文件执行器硬跑 `require(...)` 场景。\n\n## 安全说明\n\n- 这套工具主要用于开发、调试、验证\n- 它们依赖应用内 Receiver 接收外部 broadcast\n- 在生产环境中应谨慎暴露这类调试入口\n","isInternal":false,"tokens":5852,"sizeBytes":18346},{"name":"JS_ADB_README.md","path":"tools/adb/JS_ADB_README.md","rawUrl":"https://raw.githubusercontent.com/AAswordman/Operit/HEAD/tools/adb/JS_ADB_README.md","title":"Adb Skill","category":"anthropic-skill","format":"markdown","content":"# ADB JavaScript Executor\n\nThis repo's ADB JS executors are the main **device-side JavaScript runtime launchers** for Operit.\n\nThey are used for:\n\n- directly running JS on a real Android device during development\n- debugging exported JS functions without a full package import cycle\n- validating sandbox runtime behavior and structured results\n- running JS bridge / script-mode / smoke tests from `app/src/androidTest/js`\n- reproducing device-only runtime bugs quickly\n\nFor direct whole-script execution without specifying an exported function, use `run_sandbox_script.sh` / `run_sandbox_script.bat`.\n\n## Features\n\n- Push JavaScript files to Android devices using ADB\n- Run JS directly inside the Operit Android runtime\n- Execute specified JavaScript functions\n- Execute complete sandbox scripts\n- Execute a whole JS directory with local module dependencies\n- Support for JSON parameter passing\n- Temporary file option (auto-deletion after execution)\n- Implementations in Shell script, Windows Batch file, and Python script\n- **Device selection for multi-device setups**\n- Structured result capture instead of fragile log scraping\n- Useful as both a **runtime debugging launcher** and a **JS bridge test harness**\n\n## Tool Roles\n\nIn this repo, the following tools form the main on-device JS execution workflow:\n\n- `tools/adb/execute_js.bat` / `tools/adb/execute_js.sh`\n The main single-file runtime launcher.\n Pushes one JS file to the Android device and executes an exported function inside the Operit runtime.\n This is the most direct tool for device-side JS debugging.\n- `tools/adb/execute_js_dir.bat` / `tools/adb/execute_js_dir.sh`\n The directory-entry launcher.\n Bundles and runs a JS entry from a directory, so local `require(...)` chains and test suites work.\n- `tools/adb/run_sandbox_script.bat` / `tools/adb/run_sandbox_script.sh`\n The script-mode launcher.\n Runs top-level sandbox script code directly instead of calling an exported function.\n\nThis makes them suitable for:\n\n- directly running and debugging JS on Android\n- validating `JsEngine` behavior on a real device\n- reproducing package/runtime bugs quickly\n- debugging package tools without a full app rebuild loop\n- running JS-side contract tests and smoke tests under `app/src/androidTest/js`\n\n## JS Test Suites In This Repo\n\nThe directory [app/src/androidTest/js](/d:/Code/prog/assistance/app/src/androidTest/js) contains real JS runtime tests and probes, including:\n\n- bridge contract tests\n- bridge edge-case tests\n- script-mode contract tests\n- browser tool smoke tests\n- ffmpeg / utility probes\n\nRepresentative locations:\n\n- [app/src/androidTest/js/com/ai/assistance/operit/core/tools/javascript/bridge_contract](/d:/Code/prog/assistance/app/src/androidTest/js/com/ai/assistance/operit/core/tools/javascript/bridge_contract)\n- [app/src/androidTest/js/com/ai/assistance/operit/core/tools/javascript/bridge_edges](/d:/Code/prog/assistance/app/src/androidTest/js/com/ai/assistance/operit/core/tools/javascript/bridge_edges)\n- [app/src/androidTest/js/com/ai/assistance/operit/core/tools/javascript/script_mode_contract](/d:/Code/prog/assistance/app/src/androidTest/js/com/ai/assistance/operit/core/tools/javascript/script_mode_contract)\n- [app/src/androidTest/js/com/ai/assistance/operit/core/tools/defaultTool/standard/browser/main.js](/d:/Code/prog/assistance/app/src/androidTest/js/com/ai/assistance/operit/core/tools/defaultTool/standard/browser/main.js)\n- [app/src/androidTest/js/com/ai/assistance/operit/util/ttscleaner/ttscleaner.js](/d:/Code/prog/assistance/app/src/androidTest/js/com/ai/assistance/operit/util/ttscleaner/ttscleaner.js)\n\n## Quick Choice\n\nIf you just want the short answer for \"which tool should I use\":\n\n- Use `execute_js.*` when you want to call one exported function from one normal `.js` file\n- Use `execute_js_dir.*` when the entry depends on sibling modules, or when you are running directory-based tests under `app/src/androidTest/js`\n- Use `run_sandbox_script.*` when you want top-level script-mode execution instead of calling an exported function\n- Use `tools/example_packages/sync_example_packages.py` when you changed an `examples/` package or toolpkg and want it synced into the real package-loading path\n- If you are debugging `operit_editor` tools such as `debug_install_toolpkg`, the usual flow is: sync with `tools/example_packages/sync_example_packages.py`, then call the debug tool with `execute_js.bat`\n\n## Prerequisites\n\n- Android SDK (ADB)\n- Android device with USB debugging enabled\n- ADB debugging permission granted on the device\n- Your application installed on the device\n\n## Quick Start\n\n### Using Shell Script (Linux/macOS)\n\n1. Make the script executable:\n```bash\nchmod +x execute_js.sh\n```\n\n2. Execute the script:\n```bash\n./execute_js.sh path/to/your/script.js functionName '{\"param1\":\"value1\"}'\n```\n\n3. Execute a whole sandbox script directly:\n```bash\n./run_sandbox_script.sh path/to/your/script.js '{\"param1\":\"value1\"}'\n```\n\n### Using Batch Script (Windows)\n\n1. Execute the batch file:\n```cmd\nexecute_js.bat path\\to\\your\\script.js functionName @params.json\n```\n\n2. Execute a whole sandbox script directly:\n```cmd\nrun_sandbox_script.bat path\\to\\your\\script.js @params.json\n```\n\n### Execute A Whole Directory (supports `require(...)`)\n\nSometimes a script needs `require('./helper')`, shared local modules, or a whole test suite layout.\nThe single-file executors only push one JS file, so this repo also provides directory-based executors.\n\nWindows:\n```cmd\ntools\\adb\\execute_js_dir.bat app\\src\\androidTest\\js com\\ai\\assistance\\operit\\util\\ttscleaner\\main.js run \"{}\"\n```\n\nLinux/macOS:\n```bash\n./tools/adb/execute_js_dir.sh app/src/androidTest/js com/ai/assistance/operit/util/ttscleaner/ttscleaner.js run '{}'\n```\n\nMore realistic examples:\n\n```cmd\ntools\\adb\\execute_js_dir.bat app\\src\\androidTest\\js com\\ai\\assistance\\operit\\core\\tools\\javascript\\bridge_contract\\bridge_contract_runner.js run @params.json\ntools\\adb\\execute_js_dir.bat app\\src\\androidTest\\js com\\ai\\assistance\\operit\\core\\tools\\defaultTool\\standard\\browser\\main.js run \"{}\"\n```\n\nYou can still pass inline JSON directly. The scripts now write that JSON into a temporary file and push it to the device, which avoids the old `adb shell am broadcast --es params ...` quoting breakage. On PowerShell, prefer single-quoted JSON like `'{\"param1\":\"value1\"}'` or use `@params.json`.\n\n### Using Python Script (Cross-platform)\n\n1. Ensure Python 3 is installed\n\n2. Execute the script:\n```bash\npython execute_js.py path/to/your/script.js functionName --params '{\"param1\":\"value1\"}'\n```\n\n3. Additional options:\n```bash\n# Specify a device directly (skip device selection prompt)\npython execute_js.py path/to/script.js functionName --device DEVICE_SERIAL\n\n# Keep the file on the device after execution\npython execute_js.py path/to/script.js functionName --keep\n```\n\n## Device Selection\n\nWhen multiple devices are connected:\n\n1. The script will display a list of available devices\n2. Enter the number corresponding to your target device\n3. All ADB operations will be performed on the selected device\n\nExample:\n```\nChecking connected devices...\n1: emulator-5554\n2: 192.168.1.100:5555\nEnter device number (1-2): \n```\n\n## Examples\n\n### 1. Execute the greeting function\n\n```bash\n# Linux/macOS\n./execute_js.sh test_script.js sayHello '{\"name\":\"John\"}'\n\n# Windows\nexecute_js.bat test_script.js sayHello @params.json\n\n# Python (any platform)\npython execute_js.py test_script.js sayHello --params '{\"name\":\"John\"}'\n```\n\n### 2. Execute the calculation function\n\n```bash\n# Linux/macOS\n./execute_js.sh test_script.js calculate '{\"num1\":10,\"num2\":5,\"operation\":\"multiply\"}'\n\n# Windows\nexecute_js.bat test_script.js calculate @params.json\n\n# Python (any platform)\npython execute_js.py test_script.js calculate --params '{\"num1\":10,\"num2\":5,\"operation\":\"multiply\"}'\n```\n\n## Viewing Execution Results\n\nThe executor now waits for a dedicated structured result file instead of scraping `adb logcat`.\nAfter execution it prints a JSON payload containing:\n\n- `success`\n- `result`\n- `error`\n- `events` (including `console.log/info/warn/error` and intermediate updates)\n- `durationMs`\n\nThis is especially useful for JS runtime tests, because failures come back as structured payloads rather than \"check logcat manually\".\n\nYou can adjust the wait timeout with:\n\n```bash\nOPERIT_RESULT_WAIT_SECONDS=30 ./execute_js.sh path/to/your/script.js functionName '{\"param1\":\"value1\"}'\n```\n\n## Sandbox Script Debug Notes\n\nWhen you use `run_sandbox_script.sh` / `run_sandbox_script.bat`, or call package tools such as `operit_editor:debug_run_sandbox_script` with `source_code`, the code is executed as a **top-level script snippet**, not as `function(params) { ... }`.\n\nThat means:\n\n- Use `console.log(...)`, `console.info(...)`, `console.warn(...)`, `console.error(...)` for logs\n- Use `emit(...)` to send intermediate events\n- Use `return result` or `complete(...)` to finish with a structured result\n- Do **not** assume `params` is directly available inside `source_code`\n- Do **not** call `intermediate(...)`; the supported helper name is `emit(...)`\n\nRecommended inline snippet:\n\n```javascript\nconsole.log(\"inline debug start\");\nemit({ stage: \"inline\", ok: true });\ncomplete({\n success: true,\n message: \"inline debug finished\"\n});\n```\n\nIf you need parameter-driven logic, prefer one of these approaches:\n\n- Use `execute_js.*` and call an exported function like `function myFunc(params) { ... }`\n- Use `debug_run_sandbox_script` with `source_path` and put the logic in a real script file\n- Keep `source_code` for quick top-level smoke tests, logging, and minimal one-off checks\n\n## Purpose And Invocation\n\n### 1. What `execute_js.*` is for\n\nThis is the most direct Android-side JS runner.\n\nYou give it:\n\n- one JS file\n- one exported function name\n- one JSON parameter payload\n\nIt pushes that file to the device and calls that function inside Operit's Android JS runtime.\n\nUse it for:\n\n- single-file behavior checks\n- direct exported-function debugging\n- reproducing runtime-only device errors\n- debugging one tool implementation inside a package\n\nMost common usage:\n\n```cmd\ntools\\adb\\execute_js.bat examples\\operit_editor.js debug_install_toolpkg @params.json\n```\n\nMinimum file requirements:\n\n- the file must be valid JavaScript, not raw TypeScript\n- the target function must be exported\n- params must be passed as JSON\n\nExample:\n\n```javascript\nfunction main(params) {\n return {\n success: true,\n echo: params\n };\n}\n\nexports.main = main;\n```\n\n### 2. What `execute_js_dir.*` is for\n\nThis is the directory-entry runner.\n\nIf your entry file is not standalone and depends on local modules through `require(\"./x\")`, sibling helpers, shared runners, or directory-local test harnesses, switch to this instead of forcing the single-file runner.\n\nUse it for:\n\n- test entries under `app/src/androidTest/js`\n- bridge contract / browser smoke / harness-style test directories\n- any new multi-file JS runtime test suite you add\n\nMost common usage:\n\n```cmd\ntools\\adb\\execute_js_dir.bat app\\src\\androidTest\\js com\\ai\\assistance\\operit\\core\\tools\\javascript\\bridge_contract\\bridge_contract_runner.js run @params.json\n```\n\nCall format:\n\n```cmd\ntools\\adb\\execute_js_dir.bat [JSON params|@params_file]\n```\n\nThe key points are:\n\n- the first argument is the suite root\n- the second argument is the entry path relative to that root\n- the third argument is usually a runner function such as `run`\n\n### 3. What `run_sandbox_script.*` is for\n\nThis does not call an exported function. It runs the whole file as a top-level script.\n\nUse it for:\n\n- script-mode contract checks\n- quick `emit(...)` verification\n- quick `complete(...)` verification\n- temporary runtime probe scripts\n\nMost common usage:\n\n```cmd\ntools\\adb\\run_sandbox_script.bat temp\\probe.js @params.json\n```\n\nIf your code is naturally top-level script logic, this is usually simpler than wrapping everything in `exports.main = ...`.\n\n### 4. What `tools/example_packages/sync_example_packages.py` is for\n\nThis is not just a copy script. It is the sync entrypoint for `examples/` package development.\n\nIts main jobs are:\n\n- prebuild relevant TypeScript under `examples/` into JS\n- pack manifest-based directories into `.toolpkg`\n- sync normal `.js` or `.toolpkg` outputs into `app/src/main/assets/packages`\n- hot-reload changed packages to a connected device when available\n\nUse it when:\n\n- you changed a real package under `examples/`\n- you want package-management, sandbox package lists, or built-in loading logic to see the latest output\n- you want to validate the folder -> `.toolpkg` -> debug install path\n\nMost common usage:\n\n```cmd\nd:\\Code\\prog\\assistance\\.venv\\Scripts\\python.exe d:\\Code\\prog\\assistance\\tools\\example_packages\\sync_example_packages.py --include sidebar_bing_action\n```\n\nTo sync all syncable example items for broad validation:\n\n```cmd\nd:\\Code\\prog\\assistance\\.venv\\Scripts\\python.exe d:\\Code\\prog\\assistance\\tools\\example_packages\\sync_example_packages.py --mode test\n```\n\nTo update local assets without device hot reload:\n\n```cmd\nd:\\Code\\prog\\assistance\\.venv\\Scripts\\python.exe d:\\Code\\prog\\assistance\\tools\\example_packages\\sync_example_packages.py --include sidebar_bing_action --no-hot-reload\n```\n\n## How To Add Tests\n\nThe easy thing to get wrong is assuming every kind of test belongs in the same place. They do not.\n\n### 1. Add a single-file function test\n\nIf you only want to verify one function's logic, the lightest approach is:\n\n- write a normal JS file\n- export `main` or `run`\n- call it with `execute_js.*`\n\nThis is best for:\n\n- small logic checks\n- parameter parsing checks\n- return-shape checks\n- minimal bug reproductions\n\n### 2. Add a directory-based runtime test\n\nIf the test needs multiple local modules, put it under [app/src/androidTest/js](/d:/Code/prog/assistance/app/src/androidTest/js) and organize it as a small directory-based suite.\n\nRecommended shape:\n\n- one runner file such as `xxx_runner.js`\n- a few test files or helpers\n- the runner exports `run(params)`\n\nThen call it with:\n\n```cmd\ntools\\adb\\execute_js_dir.bat app\\src\\androidTest\\js run \"{}\"\n```\n\nThis is best for:\n\n- bridge contract tests\n- multi-module coordination\n- real runtime smoke tests\n- anything that needs local `require(...)`\n\n### 3. Add a script-mode test\n\nIf what you need to verify is:\n\n- top-level `return`\n- `emit(...)`\n- `complete(...)`\n- differences between script mode and function mode\n\nthen do not force it into an exported-function test. Write it as a script-mode file and run it with `run_sandbox_script.*`.\n\n### 4. Add validation for an `examples/` package or toolpkg\n\nIf you are adding a real package that should be loaded by the package system, the point is not only \"can this JS run\" but also \"can this package be synced, refreshed, installed, and recognized\".\n\nRecommended approach:\n\n- add or modify the `.ts`, `.js`, or manifest-based directory under `examples/`\n- if it is a directory-based package, make sure it has `manifest.json` or `manifest.hjson`\n- run `tools/example_packages/sync_example_packages.py`\n- then use `execute_js.bat` to call related debug tools, or validate inside the app\n\nIn other words:\n\n- the runners test whether JS executes correctly inside the Android runtime\n- `tools/example_packages/sync_example_packages.py` tests whether the `examples/` package enters the real package-loading path correctly\n\n## How To Use It With `tools/example_packages/sync_example_packages.py`\n\n### Scenario 1: You changed a normal JS script\n\nIn this case you usually do not need sync first.\n\nJust run:\n\n```cmd\ntools\\adb\\execute_js.bat path\\to\\script.js main @params.json\n```\n\nbecause you are validating script logic, not package loading.\n\n### Scenario 2: You changed a package under `examples/`\n\nRecommended order:\n\n1. Edit `examples/...`\n2. Run `tools/example_packages/sync_example_packages.py`\n3. Confirm the outputs were synced into `app/src/main/assets/packages`\n4. If a device is connected, also validate hot reload\n5. Then verify behavior inside the app or through debug tools\n\nThis fits:\n\n- normal `.js` packages\n- example packages that should appear in package lists\n- changes to package description, manifest, or dependency structure\n\n### Scenario 3: You changed a directory-based toolpkg\n\nThis is the case that most needs `tools/example_packages/sync_example_packages.py`.\n\nRecommended order:\n\n1. Edit `examples/`\n2. Run `tools/example_packages/sync_example_packages.py --include `\n3. Let it pack the directory into `.toolpkg`\n4. Let it sync the generated artifact into assets and the device\n5. Then verify installation through `operit_editor`'s `debug_install_toolpkg` or a related debug entry\n\nThis validates the full chain:\n\n- whether the directory packs correctly\n- whether the `.toolpkg` hot-reloads to device correctly\n- whether debug install recognizes it\n- whether the refreshed package actually enters the loading list\n\n### Scenario 4: You changed a debug tool such as `operit_editor`\n\nRecommended order:\n\n1. Sync `operit_editor` itself with `tools/example_packages/sync_example_packages.py`\n2. Prepare the package or toolpkg you want it to install\n3. Call the debug function through `execute_js.bat`\n4. Inspect the structured result for success, failure, and related warnings\n\nExample:\n\n```cmd\nd:\\Code\\prog\\assistance\\.venv\\Scripts\\python.exe d:\\Code\\prog\\assistance\\tools\\example_packages\\sync_example_packages.py --include operit_editor --include sidebar_bing_action\ntools\\adb\\execute_js.bat examples\\operit_editor.js debug_install_toolpkg @params.json\n```\n\nThis is good for validating:\n\n- whether the debug install call shape is correct\n- whether a folder packaged into `.toolpkg` installs correctly\n- whether install-time warnings or errors are returned back to the caller\n\n## Recommended Workflows\n\n### 1. Direct Android-side JS debugging\n\nUse `execute_js.bat` / `execute_js.sh` when you want to directly run and debug one JS file on the Android device.\nThis is the default choice for ordinary sandbox/package JS development.\n\n```cmd\ntools\\adb\\execute_js.bat examples\\operit_editor.js debug_install_toolpkg @params.json\n```\n\nTypical use cases:\n\n- test one exported function quickly\n- reproduce a runtime bug on device\n- verify parameter parsing / `complete(...)` / structured output\n- debug a normal `.js` package before turning it into something larger\n\n### 2. Real test suite / local-module run\n\nUse `execute_js_dir.*` when the entry file depends on sibling modules or you are running material under `app/src/androidTest/js`.\n\n```cmd\ntools\\adb\\execute_js_dir.bat app\\src\\androidTest\\js com\\ai\\assistance\\operit\\core\\tools\\javascript\\script_mode_contract\\return_object.js run \"{}\"\n```\n\n### 3. Direct sandbox snippet probe\n\nUse `run_sandbox_script.*` for quick script-mode behavior checks.\n\n```cmd\ntools\\adb\\run_sandbox_script.bat temp\\probe.js @params.json\n```\n\n## Quick Command List\n\n### 1. Run one normal exported function\n\n```cmd\ntools\\adb\\execute_js.bat examples\\my_script.js main @params.json\n```\n\n### 2. Run one `androidTest/js` directory-based test entry\n\n```cmd\ntools\\adb\\execute_js_dir.bat app\\src\\androidTest\\js com\\ai\\assistance\\operit\\core\\tools\\javascript\\bridge_contract\\bridge_contract_runner.js run @params.json\n```\n\n### 3. Run one top-level script-mode probe\n\n```cmd\ntools\\adb\\run_sandbox_script.bat temp\\probe.js @params.json\n```\n\n### 4. Sync one `examples/` package into assets and device\n\n```cmd\nd:\\Code\\prog\\assistance\\.venv\\Scripts\\python.exe d:\\Code\\prog\\assistance\\tools\\example_packages\\sync_example_packages.py --include sidebar_bing_action\n```\n\n### 5. Sync first, then call the debug installer tool\n\n```cmd\nd:\\Code\\prog\\assistance\\.venv\\Scripts\\python.exe d:\\Code\\prog\\assistance\\tools\\example_packages\\sync_example_packages.py --include operit_editor --include sidebar_bing_action\ntools\\adb\\execute_js.bat examples\\operit_editor.js debug_install_toolpkg @params.json\n```\n\n## JavaScript File Requirements\n\n- Files must be valid JavaScript (TypeScript not supported)\n- Functions must be exported (using `exports.functionName = functionName`)\n- Functions must accept a params parameter (containing the passed parameters)\n- Functions can either `return result` directly or call `complete(result)`\n\n## Required Function Example\n\n```javascript\nfunction myFunction(params) {\n // Process parameters\n const name = params.name || \"default\";\n \n // Execute business logic\n const result = `Result: ${name}`;\n \n // Return result\n return {\n success: true,\n result: result\n };\n}\n\n// Export function\nexports.myFunction = myFunction;\n```\n\n## Technical Details\n\n1. The Shell/Batch script pushes the JavaScript file to a temporary directory on the device\n2. `execute_js.bat` / `execute_js.sh` directly execute that pushed file inside the Android app's JS runtime\n3. `execute_js_dir.*` bundles a directory entry first, so local modules can be resolved in one pushed artifact\n4. Inline JSON parameters are first written to a temp JSON file, then pushed to the device as `params_file_path`\n5. An ADB broadcast is sent to the application with the execution request\n6. The application's BroadcastReceiver receives the request and uses `JsEngine` to execute the function or whole script\n7. Execution results are written to a dedicated JSON file on the device\n8. The executor waits for that file, prints it, and then cleans it up\n\n## Troubleshooting\n\n### Common Issues\n\n1. **ADB command not found** \n Ensure the Android SDK's platform-tools directory is in your PATH environment variable.\n\n2. **No devices detected**\n - Make sure the device is connected\n - Ensure USB debugging is enabled\n - Check that the computer is authorized for USB debugging\n\n3. **Broadcast sent but function not executed**\n - Check the logs for error messages\n - Confirm the application is running\n - Verify the receiver is correctly registered\n\n4. **JavaScript errors**\n - Check for TypeScript-specific syntax (like type annotations)\n - Ensure functions are properly exported\n - Verify parameter formats are correct\n \n## Required Permissions\n\nThis feature requires the following permissions:\n\n- Read and write external storage\n- Permission to receive broadcasts\n\n## Security Considerations\n\n- This feature should only be used for development and debugging purposes\n- In production environments, this feature should be disabled or restricted to prevent security risks \n","isInternal":false,"tokens":5272,"sizeBytes":22472},{"name":"COMPOSE_DSL_DEBUG_README.md","path":"tools/compose_dsl/COMPOSE_DSL_DEBUG_README.md","rawUrl":"https://raw.githubusercontent.com/AAswordman/Operit/HEAD/tools/compose_dsl/COMPOSE_DSL_DEBUG_README.md","title":"Compose_dsl Skill","category":"anthropic-skill","format":"markdown","content":"# Compose DSL UI Dump\n\n## 用途\n\n`dump_current_compose_dsl_ui.bat` 用来抓取当前正在显示的 `compose_dsl` 页面运行时快照，方便排查：\n\n- 脚本输出的组件树是否正确\n- 宿主解析后的树是否一致\n- 布局坐标和尺寸是否符合预期\n- 当前页面 `state` / `memo` 是否异常\n\n这套工具适合排查“结构看起来对，但界面显示不对”的问题。\n\n## 使用方法\n\n1. 用宿主打开你要调试的 `compose_dsl` 页面。\n2. 等页面进入你想观察的状态。\n3. 运行：\n\n```bat\nd:\\Code\\prog\\assistance\\tools\\compose_dsl\\dump_current_compose_dsl_ui.bat\n```\n\n## 前提条件\n\n- 已安装并可使用 `adb`\n- 至少连接了一台可调试设备\n- 设备上的宿主版本已经包含当前调试导出逻辑\n- 设备上已安装 `com.ai.assistance.operit.debug` 或 `com.ai.assistance.operit`；脚本未指定时优先使用 Debug 包\n\n如果连接了多台设备，脚本会提示选择目标设备。\n\n如果 Debug 和 Release APK 同时安装，可以用环境变量指定目标：\n\n```bat\nset OPERIT_APP_PACKAGE=com.ai.assistance.operit\nd:\\Code\\prog\\assistance\\tools\\compose_dsl\\dump_current_compose_dsl_ui.bat\n```\n\n## 导出位置\n\n脚本会把文件拉回本地目录：\n\n```text\nd:\\Code\\prog\\assistance\\debug_output\\compose_dsl_dump\\<时间戳>\\\n```\n\n例如：\n\n```text\nd:\\Code\\prog\\assistance\\debug_output\\compose_dsl_dump\\20260425-153457\\\n```\n\n## 文件说明\n\n- `dump_manifest.json`\n 当前页面的基础信息，包括包名、模块名、phase、是否仍在 loading / dispatching。\n\n- `source_script.js`\n 当前页面实际执行的 UI 脚本源码。\n\n- `raw_render_result.txt`\n JS 原始 render 返回值的文本形式。\n\n- `raw_render_result.json`\n 如果原始返回值可以解析为 JSON，这里会保存格式化后的版本。\n\n- `parsed_render_result.json`\n 宿主解析后的完整 render 结果。\n\n- `compose_tree.txt`\n 解析后的组件树，可快速看结构。\n\n- `compose_tree.json`\n 组件树的 JSON 形式。\n\n- `layout_nodes.txt`\n 每个节点的真实布局信息，包括 `x / y / width / height`。\n\n- `layout_nodes.json`\n 布局信息的 JSON 形式。\n\n- `compose_layout_tree.txt`\n “组件树 + 布局信息”合并后的可读版本。\n\n- `state.json`\n 当前页面状态。\n\n- `memo.json`\n 当前页面 memo。\n\n## 推荐排查顺序\n\n1. 先看 `dump_manifest.json`\n 确认抓到的是不是当前页面，以及页面是不是已经稳定。\n\n2. 再看 `compose_tree.txt`\n 判断脚本输出结构是否正确。\n\n3. 再看 `layout_nodes.txt` 或 `compose_layout_tree.txt`\n 判断真实布局是不是出了问题。\n\n4. 如果怀疑状态异常，再看 `state.json`\n 确认是不是脚本状态导致界面不对。\n\n5. 如果怀疑宿主解析有偏差，再对比：\n `raw_render_result.json` 和 `parsed_render_result.json`\n\n## 常见场景\n\n- 文本、图标、按钮没有居中\n- `weight`、`fillMaxWidth`、`padding` 没按预期生效\n- `onLoad` 后页面状态和预期不一致\n- 脚本写出来的树和宿主最终理解的树不同\n\n## 注意事项\n\n- 这套工具抓的是“当前正在显示的页面快照”，不是历史页面。\n- 如果页面还在频繁重组或异步加载，建议等稳定后再抓一次。\n- 如果宿主调试导出逻辑有更新，需要重新安装宿主后才能看到新导出字段。\n","isInternal":false,"tokens":1118,"sizeBytes":3377},{"name":"issues_open_ai.md","path":"tools/github/issues_open_ai.md","rawUrl":"https://raw.githubusercontent.com/AAswordman/Operit/HEAD/tools/github/issues_open_ai.md","title":"Github Skill","category":"anthropic-skill","format":"markdown","content":"# Issue Triage Report\n\n## Overall summary (counts by category, quick highlights)\n**总计议题数：** 45 个 (状态：open)\n\n**按类别统计：**\n* **Bug (缺陷):** 7 个 (含 3 个 P0)\n* **无障碍/权限:** 6 个 (含 2 个 P1)\n* **用户界面 (UI):** 11 个 (含 2 个 P1)\n* **工具/功能管理:** 9 个 (均为 P1/P2)\n* **工具/自动化:** 6 个 (含 2 个 P1)\n* **模型/API 集成:** 3 个 (含 1 个 P1)\n* **国际化 (i18n):** 1 个 (P1)\n* **配置/同步:** 1 个 (P1)\n* **模型 / AI 核心:** 2 个 (含 1 个 P1)\n* **数据导入/导出:** 1 个 (P2)\n* **应用分发:** 1 个 (P2)\n* **终端:** 1 个 (P1，与 UI 类别 #237 重叠)\n\n**快速亮点：**\n* **高优先级缺陷 (P0):** 存在 3 个关键 Bug，均导致核心的 UI 信息获取/自动化功能在特定系统上完全失效 (#125, #101, #67)。\n* **权限与兼容性问题突出：** 多个 P1 议题涉及 Android 系统（特别是 ColorOS、MIUI、鸿蒙）的权限授予失败、服务连接异常或文件访问问题 (#306, #283, #317)。\n* **功能建议集中：** 大量 P1/P2 议题围绕 **UI/UX 优化**、**自动化功能增强**、**AI 执行效率提升**（如安静模式、变量存储）和**配置管理**（如对话绑定模型、配置同步）提出建议。\n* **模型集成问题：** 存在通过 oneAPI 调用智谱模型失败 (#277) 和本地 llama.cpp 连接问题 (#258)，影响模型可用性。\n\n## Top priorities (P0 then P1)\n\n**P0 (关键缺陷，需立即调查):**\n1. **#125**: UI信息始终是Operit AI应用的 - AI 操作其他应用时获取自身 UI 信息，导致核心自动化功能失效。\n2. **#101**: [bug] UI调试工具无法获取当前屏幕内容 - 在 ColorOS 上触发系统返回，无法获取屏幕内容。\n3. **#67**: Miui 14.0.4 在debugger和root模式下均无法获取页面元素 - 在 MIUI 上 UI 数据获取完全失败。\n\n**P1 (高优先级功能/缺陷):**\n1. **#306**: [BUG]由于无障碍辅助app未申请任何权限，导致ColorOS无法解除权限限制 - 权限流程阻塞，影响核心功能启用。\n2. **#312**: English selected but large parts of UI still in Chinese - 国际化不完整，影响非中文用户体验。\n3. **#266**: 角色切换后主界面历史对话不显示，仅在悬浮窗显示 - 数据展示不一致，影响使用连贯性。\n4. **#283**: Bug: 无障碍服务已开启但AI助手接口服务显示未连接 - 服务状态指示错误，误导用户。\n5. **#317**: [bug]在Android8中，应用无法读取，修改Android设备本机中的文件 - 基础文件功能在特定系统失效。\n6. **#277**: 使用oneapi集成智谱code模型调用失败 - 第三方模型集成失败，影响功能可用性。\n7. **#321**: 添加配置同步功能 - 重要的用户体验增强功能，设计复杂度高。\n8. **#237**: 建议 (综合性UI/功能建议，含终端SSH想法)\n9. **#10**: 十条建议 (基础功能与UI改进建议集合)\n10. **#248**: 小功能拓展建议 (自动截图、连续对话、定时提醒等)\n11. **#35**: 请增加识图找图功能... (补充UI自动化能力)\n12. **#216**: Local llm implementation cpu/gpu/npu (支持本地LLM)\n13. **#165**: code_runner中的代码显示bug (显示格式错误)\n\n## By category (each category heading, list issues)\n\n### Bug (缺陷)\n* **#125 (P0)**: ui信息始终是Operit AI应用的 - AI操作其他应用时，获取的UI信息错误（始终是本应用），导致功能失效。 **行动：调查**\n* **#101 (P0)**: [bug] UI调试工具无法获取当前屏幕内容 - 在特定系统（Android 10 ColorOS）上，调用UI调试工具会触发系统返回，无法获取内容。 **行动：调查**\n* **#67 (P0)**: Miui 14.0.4 在debugger和root模式下均无法获取页面元素 - 在MIUI系统上，UI数据获取完全失败。 **行动：调查**\n* **#165 (P1)**: code_runner中的代码显示bug - code_runner显示代码时包含了前后标签，而非纯净代码。 **行动：修复**\n* **#27 (P2)**: 屏幕识别在某个软件里识别不出来东西 - 屏幕识别功能在特定软件中失效。 **行动：调查**\n* **#291 (P2)**: 导入聊天记录报错 - 导入聊天记录时失败，报错“未找到有效聊天记录”或“格式转换失败”。 **行动：调查**\n* **#263 (P2)**: 搜索引擎使用结果提取的问题 - 使用百度搜索后，提取搜索结果详情页内容时经常遇到 404 错误。 **行动：调查**\n\n### 无障碍/权限\n* **#306 (P1)**: [BUG]由于无障碍辅助app未申请任何权限，导致ColorOS无法解除权限限制 - 在 ColorOS 上，由于应用未申请常规权限，导致无法在设置中解除权限限制，进而无法授予无障碍权限。 **行动：修复**\n* **#283 (P1)**: Bug: 无障碍服务已开启但AI助手接口服务显示未连接 - 无障碍服务已开启，但应用内显示 AI 助手接口服务未连接。 **行动：调查**\n* **#317 (P1)**: [bug]在Android8中，应用无法读取，修改Android设备本机中的文件 - 在 Android 8 (鸿蒙2) 设备上，应用无法读写设备本地文件（尽管 `code_runner` 和 `shell` 可用）。 **行动：调查**\n* **#316 (P2)**: 关于APP被关联启动 - 应用在关闭状态下被关联启动并弹出无法滑掉的通知，影响用户体验，寻求关闭方法。 **行动：调查**\n* **#307 (P2)**: 语音助手功能可用性低 - 语音助手存在多个问题：手势启动后不能直接语音输入、识别失败率高、建议调用系统接口、界面图标辨识度低。 **行动：调查**\n* **#250 (部分内容) (P2)**: 自动化任务遇到双开软件提示或系统权限弹窗时无法识别并选择。 **行动：设计**\n\n### 用户界面 (UI)\n* **#266 (P1)**: 角色切换后主界面历史对话不显示，仅在悬浮窗显示 - 切换角色卡后，主界面无法加载对应历史对话，仅悬浮窗部分显示，数据不同步。 **行动：修复**\n* **#320 (P1)**: 1、你一个对话问问题... - 包含多个 UI 交互问题：多对话卡顿、waifu模式表格显示异常、窗口模式切换冲突、颜色选择器可视化不足。 **行动：调查**\n* **#237 (P1)**: 建议 - 包含多项UI改进建议，如对话框背景、权限管理等。**设计**\n* **#10 (P1)**: 十条建议 - 包含多项基础功能与UI改进建议，如输入交互、导航、主题等。**设计**\n* **#268 (P2)**: 全屏\n","isInternal":false,"tokens":2397,"sizeBytes":6496},{"name":"issues_open.md","path":"tools/github/issues_open.md","rawUrl":"https://raw.githubusercontent.com/AAswordman/Operit/HEAD/tools/github/issues_open.md","title":"Github Skill","category":"anthropic-skill","format":"markdown","content":"# GitHub Issues (AAswordman/Operit)\n\nState: `open`\nCount: `42`\n\n- #321 [添加配置同步功能](https://github.com/AAswordman/Operit/issues/321) (open)\n - comments: 1 | updated: 2026-01-11T07:26:48Z\n- #312 [English selected but large parts of UI still in Chinese (agents/artifacts/settings)](https://github.com/AAswordman/Operit/issues/312) (open)\n - comments: 3 | updated: 2026-01-10T11:28:06Z\n- #320 [1、你一个对话问问题，新打开一个对话再问一个，两个对话都会卡住。 2、waifu模式就不会发完整表格了，会把表格拆分成一行一行 3、小窗模式跟系统小窗跟最大模式有时候会冲突，在小窗模式显示回复，放大以后就不显示了，过一会突然卡出来。 4、各个地方的颜色选择变化时来点可视化就舒服了 5、调用shizuku时就巨慢，一点小小的任务要好久](https://github.com/AAswordman/Operit/issues/320) (open)\n - comments: 0 | updated: 2026-01-09T08:31:56Z\n- #319 [折叠对话](https://github.com/AAswordman/Operit/issues/319) (open)\n - comments: 0 | updated: 2026-01-07T18:13:40Z\n- #318 [一些功能性建议](https://github.com/AAswordman/Operit/issues/318) (open)\n - comments: 0 | updated: 2026-01-07T17:57:06Z\n- #317 [[bug]在Android8中，应用无法读取，修改Android设备本机中的文件](https://github.com/AAswordman/Operit/issues/317) (open)\n - comments: 0 | updated: 2026-01-06T14:21:18Z\n- #316 [关于APP被关联启动](https://github.com/AAswordman/Operit/issues/316) (open)\n - comments: 0 | updated: 2026-01-05T10:32:40Z\n- #311 [一些建议](https://github.com/AAswordman/Operit/issues/311) (open)\n - comments: 0 | updated: 2026-01-03T03:47:49Z\n- #277 [使用oneapi集成智谱code模型调用失败](https://github.com/AAswordman/Operit/issues/277) (open)\n - comments: 5 | updated: 2026-01-01T07:46:15Z\n- #307 [语音助手功能可用性低](https://github.com/AAswordman/Operit/issues/307) (open)\n - comments: 2 | updated: 2025-12-31T14:58:03Z\n- #306 [[BUG]由于无障碍辅助app未申请任何权限，导致ColorOS无法解除权限限制](https://github.com/AAswordman/Operit/issues/306) (open)\n - comments: 1 | updated: 2025-12-31T14:13:34Z\n- #300 [部分国行应用获取页面信息不正确](https://github.com/AAswordman/Operit/issues/300) (open)\n - comments: 2 | updated: 2025-12-31T01:56:23Z\n- #295 [记忆与记忆之间的链接只有创建和删除，没有修改](https://github.com/AAswordman/Operit/issues/295) (open)\n - comments: 1 | updated: 2025-12-21T02:08:50Z\n- #273 [建议上架到fdroid](https://github.com/AAswordman/Operit/issues/273) (open)\n - comments: 3 | updated: 2025-12-19T13:05:17Z\n- #291 [导入聊天记录报错](https://github.com/AAswordman/Operit/issues/291) (open)\n - comments: 0 | updated: 2025-12-18T08:22:29Z\n- #287 [【Request】对话绑定模型配置](https://github.com/AAswordman/Operit/issues/287) (open)\n - comments: 1 | updated: 2025-12-17T17:39:36Z\n- #283 [Bug: 无障碍服务已开启但AI助手接口服务显示未连接](https://github.com/AAswordman/Operit/issues/283) (open)\n - comments: 1 | updated: 2025-12-17T17:37:25Z\n- #267 [功能建议：操作屏幕录制、绘图功能、TIM适配等四大功能增强](https://github.com/AAswordman/Operit/issues/267) (open)\n - comments: 1 | updated: 2025-12-11T03:10:36Z\n- #265 [功能建议——安静模式](https://github.com/AAswordman/Operit/issues/265) (open)\n - comments: 1 | updated: 2025-12-11T02:17:10Z\n- #268 [全屏编辑提示词等内容时底部不会被输入法抬起](https://github.com/AAswordman/Operit/issues/268) (open)\n - comments: 0 | updated: 2025-12-10T01:08:33Z\n- #266 [角色切换后主界面历史对话不显示，仅在悬浮窗显示](https://github.com/AAswordman/Operit/issues/266) (open)\n - comments: 3 | updated: 2025-12-08T11:40:49Z\n- #264 [功能建议--变量](https://github.com/AAswordman/Operit/issues/264) (open)\n - comments: 1 | updated: 2025-12-07T11:38:13Z\n- #250 [一些建议和发现的问题](https://github.com/AAswordman/Operit/issues/250) (open)\n - comments: 6 | updated: 2025-12-07T09:21:04Z\n- #263 [搜索引擎使用结果提取的问题](https://github.com/AAswordman/Operit/issues/263) (open)\n - comments: 0 | updated: 2025-12-07T09:13:08Z\n- #258 [为什么请求不到llama.cpp啊](https://github.com/AAswordman/Operit/issues/258) (open)\n - comments: 1 | updated: 2025-11-22T07:56:22Z\n- #237 [建议](https://github.com/AAswordman/Operit/issues/237) (open)\n - labels: enhancement | comments: 3 | updated: 2025-11-12T06:07:20Z\n- #248 [小功能拓展建议](https://github.com/AAswordman/Operit/issues/248) (open)\n - comments: 0 | updated: 2025-11-08T05:35:45Z\n- #216 [Local llm implementation cpu/gpu/npu](https://github.com/AAswordman/Operit/issues/216) (open)\n - comments: 1 | updated: 2025-10-20T04:43:49Z\n- #214 [关于悬浮窗的建议](https://github.com/AAswordman/Operit/issues/214) (open)\n - comments: 0 | updated: 2025-10-15T00:55:58Z\n- #10 [十条建议](https://github.com/AAswordman/Operit/issues/10) (open)\n - labels: enhancement, good first issue | comments: 29 | updated: 2025-10-12T17:22:26Z\n- #165 [code_runner中的代码显示bug](https://github.com/AAswordman/Operit/issues/165) (open)\n - comments: 1 | updated: 2025-08-29T17:23:20Z\n- #138 [建议](https://github.com/AAswordman/Operit/issues/138) (open)\n - comments: 5 | updated: 2025-08-06T14:56:10Z\n- #125 [ui信息始终是Operit AI应用的](https://github.com/AAswordman/Operit/issues/125) (open)\n - comments: 8 | updated: 2025-08-03T17:03:38Z\n- #115 [小建议](https://github.com/AAswordman/Operit/issues/115) (open)\n - comments: 4 | updated: 2025-07-05T02:40:07Z\n- #35 [请增加识图找图功能，解决UI Automator识别不了画布上的自定义组件的缺陷。](https://github.com/AAswordman/Operit/issues/35) (open)\n - comments: 1 | updated: 2025-07-04T16:25:28Z\n- #108 [建议和bug](https://github.com/AAswordman/Operit/issues/108) (open)\n - comments: 8 | updated: 2025-07-02T04:58:07Z\n- #107 [几条建议](https://github.com/AAswordman/Operit/issues/107) (open)\n - labels: enhancement | comments: 1 | updated: 2025-06-30T18:05:48Z\n- #101 [[bug] UI调试工具无法获取当前屏幕内容](https://github.com/AAswordman/Operit/issues/101) (open)\n - comments: 1 | updated: 2025-06-28T10:09:36Z\n- #90 [能否在工具箱中添加一个查看触摸坐标的功能](https://github.com/AAswordman/Operit/issues/90) (open)\n - comments: 1 | updated: 2025-06-22T05:22:40Z\n- #78 [一些建议](https://github.com/AAswordman/Operit/issues/78) (open)\n - comments: 8 | updated: 2025-06-20T15:03:01Z\n- #67 [Miui 14.0.4 在debugger和root模式下均无法获取页面元素](https://github.com/AAswordman/Operit/issues/67) (open)\n - labels: bug | comments: 12 | updated: 2025-06-20T11:06:01Z\n- #27 [屏幕识别在某个软件里识别不出来东西](https://github.com/AAswordman/Operit/issues/27) (open)\n - comments: 1 | updated: 2025-06-07T05:38:57Z\n","isInternal":false,"tokens":2707,"sizeBytes":6989},{"name":"package.json","path":"tools/mcp_bridge/package.json","rawUrl":"https://raw.githubusercontent.com/AAswordman/Operit/HEAD/tools/mcp_bridge/package.json","title":"mcp-tcp-bridge","category":"anthropic-skill","format":"json","content":"{\n \"name\": \"mcp-tcp-bridge\",\n \"version\": \"1.0.0\",\n \"description\": \"将STDIO型MCP服务器桥接到TCP端口\",\n \"main\": \"dist/index.js\",\n \"scripts\": {\n \"build\": \"tsc && pnpm run bundle && pnpm run copy\",\n \"bundle\": \"ncc build dist/index.js -o bundle && ncc build dist/spawn-helper.js -o bundle-helper\",\n \"copy\": \"node -e \\\"require('fs').copyFileSync('bundle/index.js', '../../app/src/main/assets/bridge/index.js')\\\" && node -e \\\"require('fs').copyFileSync('bundle-helper/index.js', '../../app/src/main/assets/bridge/spawn-helper.js')\\\"\",\n \"start\": \"node dist/index.js\",\n \"dev\": \"ts-node index.ts\",\n \"test\": \"echo \\\"Error: no test specified\\\" && exit 1\"\n },\n \"keywords\": [\n \"mcp\",\n \"bridge\",\n \"tcp\",\n \"stdio\"\n ],\n \"author\": \"\",\n \"license\": \"MIT\",\n \"dependencies\": {\n \"@modelcontextprotocol/sdk\": \"1.30.0\"\n },\n \"devDependencies\": {\n \"@types/node\": \"^18.0.0\",\n \"@vercel/ncc\": \"^0.38.1\",\n \"ts-node\": \"^10.9.1\",\n \"typescript\": \"^5.0.0\"\n }\n}\n","frontmatter":{"name":"mcp-tcp-bridge","version":"1.0.0","description":"将STDIO型MCP服务器桥接到TCP端口","main":"dist/index.js","scripts":{"build":"tsc && pnpm run bundle && pnpm run copy","bundle":"ncc build dist/index.js -o bundle && ncc build dist/spawn-helper.js -o bundle-helper","copy":"node -e \"require('fs').copyFileSync('bundle/index.js', '../../app/src/main/assets/bridge/index.js')\" && node -e \"require('fs').copyFileSync('bundle-helper/index.js', '../../app/src/main/assets/bridge/spawn-helper.js')\"","start":"node dist/index.js","dev":"ts-node index.ts","test":"echo \"Error: no test specified\" && exit 1"},"keywords":["mcp","bridge","tcp","stdio"],"author":"","license":"MIT","dependencies":{"@modelcontextprotocol/sdk":"1.30.0"},"devDependencies":{"@types/node":"^18.0.0","@vercel/ncc":"^0.38.1","ts-node":"^10.9.1","typescript":"^5.0.0"}},"isInternal":false,"tokens":320,"sizeBytes":1083},{"name":"tsconfig.json","path":"tools/mcp_bridge/tsconfig.json","rawUrl":"https://raw.githubusercontent.com/AAswordman/Operit/HEAD/tools/mcp_bridge/tsconfig.json","title":"Mcp_bridge Skill","category":"anthropic-skill","format":"json","content":"{\n \"compilerOptions\": {\n \"target\": \"es2020\",\n \"module\": \"NodeNext\",\n \"outDir\": \"./dist\",\n \"rootDir\": \".\",\n \"strict\": true,\n \"esModuleInterop\": true,\n \"skipLibCheck\": true,\n \"forceConsistentCasingInFileNames\": true,\n \"resolveJsonModule\": true,\n \"moduleResolution\": \"NodeNext\",\n \"sourceMap\": true,\n \"declaration\": true,\n \"downlevelIteration\": true\n },\n \"include\": [\n \"*.ts\"\n ],\n \"exclude\": [\n \"node_modules\",\n \"dist\"\n ]\n}","frontmatter":{"compilerOptions":{"target":"es2020","module":"NodeNext","outDir":"./dist","rootDir":".","strict":true,"esModuleInterop":true,"skipLibCheck":true,"forceConsistentCasingInFileNames":true,"resolveJsonModule":true,"moduleResolution":"NodeNext","sourceMap":true,"declaration":true,"downlevelIteration":true},"include":["*.ts"],"exclude":["node_modules","dist"]},"isInternal":false,"tokens":141,"sizeBytes":549},{"name":"README.md","path":"tools/compose_dsl/README.md","rawUrl":"https://raw.githubusercontent.com/AAswordman/Operit/HEAD/tools/compose_dsl/README.md","title":"compose_dsl Documentation","category":"plugin-manifest","format":"markdown","content":"# compose_dsl artifact generator\n\nGenerates compose_dsl artifacts from Compose source jars in Gradle cache.\n\n- Kotlin renderer registry:\n - `app/src/main/java/com/ai/assistance/operit/ui/common/composedsl/ToolPkgComposeDslGeneratedRegistry.kt`\n- Kotlin renderers:\n - `app/src/main/java/com/ai/assistance/operit/ui/common/composedsl/ToolPkgComposeDslGeneratedRenderers.kt`\n- TypeScript generated bindings:\n - `examples/types/compose-dsl.material3.generated.d.ts`\n\nRun:\n\n```bash\npython tools/compose_dsl/generate_compose_dsl_artifacts.py\n```\n\nNotes:\n- Source jars are resolved from `~/.gradle/caches/modules-2/files-2.1`.\n- If jars are missing, sync/build once to download dependencies.\n- Generator behavior:\n - Keeps dedicated renderers for core complex nodes (TextField/Icon/Card/Surface, etc.).\n - Auto-discovers additional public `@Composable` functions from Material3/Foundation and\n generates generic renderers/registry/TS props when required params are mappable.\n - `ToolPkgComposeDslGeneratedRenderers.kt.tpl` is now a thin scaffold with helper functions;\n component renderers are injected at `// __GENERATED_COMPONENT_RENDERERS__`.\n","isInternal":false,"tokens":283,"sizeBytes":1151},{"name":"README.md","path":"tools/mcp_bridge/README.md","rawUrl":"https://raw.githubusercontent.com/AAswordman/Operit/HEAD/tools/mcp_bridge/README.md","title":"mcp_bridge Documentation","category":"plugin-manifest","format":"markdown","content":"# MCP TCP 桥接器\n\n这个工具只负责基于 STDIO 的本地 MCP 服务器与 TCP 客户端之间的桥接，让无法直接访问命名管道(FIFO)的客户端，例如 Android 应用，能够与本地进程通信。\n\n远程 HTTP Stream 和 SSE MCP 服务由 Android 端的 Kotlin MCP SDK 直接连接，不经过 bridge。\n\n## 功能特点\n\n- 将STDIO型MCP服务器桥接到TCP端口\n- 支持并发连接\n- 自动重启崩溃的MCP进程\n- 优雅地处理连接错误和进程终止\n- 详细的日志记录\n\n## 安装\n\n```bash\n# 在项目根目录安装工作区依赖\npnpm install\n\n# 编译 bridge 并同步 Android assets\npnpm --dir tools/mcp_bridge run build\n```\n\n`tools/mcp_bridge` 的依赖由根目录 `pnpm-lock.yaml` 统一锁定。构建会更新\n`app/src/main/assets/bridge/index.js` 和 `app/src/main/assets/bridge/spawn-helper.js`。\n\n## 使用方法\n\n### 基本用法\n\n```bash\n# 使用默认配置启动\npnpm --dir tools/mcp_bridge start\n```\n\n这将在默认端口8752上启动桥接器，连接到`../your-mcp-server.js`。\n\n### 高级用法\n\n您可以通过命令行参数自定义桥接器：\n\n```bash\n# 格式\npnpm --dir tools/mcp_bridge start -- [端口] [命令] [参数...]\n\n# 示例：在端口9000上启动，连接到Python MCP服务器\npnpm --dir tools/mcp_bridge start -- 9000 python ../python_mcp_server.py\n\n# 示例：连接到Java MCP服务器\npnpm --dir tools/mcp_bridge start -- 8752 java -jar ../java_mcp_server.jar\n```\n\n### 在代码中使用\n\n您也可以在其他Node.js应用中使用这个桥接器：\n\n```typescript\nimport McpBridge from './path/to/bridge';\n\nconst bridge = new McpBridge({\n port: 8752,\n host: '127.0.0.1',\n mcpCommand: 'node',\n mcpArgs: ['../your-mcp-server.js'],\n verbose: true\n});\n\nbridge.start();\n```\n\n## 在Termux中使用\n\n在Termux环境中，可以按以下步骤设置：\n\n```bash\n# 安装Node.js\npkg install nodejs\n\n# 克隆或下载此项目\ngit clone <项目URL>\ncd <项目目录>\n\n# 安装根工作区依赖\npnpm install\n\n# 编译并同步 Android assets\npnpm --dir tools/mcp_bridge run build\n\n# 启动桥接器\npnpm --dir tools/mcp_bridge start -- 8752 node ../your-mcp-server.js\n```\n\n## Android客户端示例\n\n以下是Android客户端连接到MCP桥接器的示例代码：\n\n```kotlin\nimport kotlinx.coroutines.Dispatchers\nimport kotlinx.coroutines.withContext\nimport java.io.BufferedReader\nimport java.io.InputStreamReader\nimport java.io.PrintWriter\nimport java.net.Socket\nimport org.json.JSONObject\n\nclass McpClient {\n private val host = \"127.0.0.1\"\n private val port = 8752\n \n suspend fun sendRequest(method: String, params: JSONObject): JSONObject = withContext(Dispatchers.IO) {\n Socket(host, port).use { socket ->\n val input = BufferedReader(InputStreamReader(socket.getInputStream()))\n val output = PrintWriter(socket.getOutputStream(), true)\n \n // 创建JSONRPC请求\n val requestId = System.currentTimeMillis().toString()\n val request = JSONObject().apply {\n put(\"jsonrpc\", \"2.0\")\n put(\"id\", requestId)\n put(\"method\", method)\n put(\"params\", params)\n }\n \n // 发送请求\n output.println(request.toString())\n \n // 读取响应\n val response = input.readLine()\n JSONObject(response)\n }\n }\n}\n```\n\n## 注意事项\n\n- 确保MCP服务器程序已正确安装并可执行\n- 桥接器应当与内部网络一起使用，不要暴露到公共互联网\n- 对于生产环境，考虑添加认证和加密层\n- 在Android环境中，确保应用有INTERNET权限\n","isInternal":false,"tokens":1047,"sizeBytes":3685}],"systemPromptSnippet":"\n\n# AGENTS.md\n\n执行准则章节是对Agent, AI 或 你 的限制，不是对项目或者软件的限制，无需写入文档\n## 执行准则\n- 默认不要执行编译、构建或测试命令。\n- 只有在用户明确要求时，才执行编译/构建/测试（例如 `./gradlew :app:compileDebugKotlin`、`npm run build`、`pnpm run build`）。\n- 创建分支时，必须遵守 `docs/doc-src/dev-core/CONTRIBUTING.md` 中“创建 Pull Request”的分支命名规范。\n\n当针对用户接口的方案更换时，一定要询问用户是否该版本为已发布版本。如果是，请做向前兼容。如果不是，请彻彻底底把老的方案的一切代码全部清理，除非是还能用到的一些部分就继续留着。\nDon't Break Userspace ，但是开发中能内部消解的方案更换不算，只要用户能尽可能拿到一样的接口就行\n但是需要给协作者必要的便利，提供恰当的文档说明和ci脚本\n\n如果是方案迭代，则只要在原来的基础上进行正常增删即可。\n\n除非用户要求，禁止写一切的回退代码。优先查找真正的发生原因。这是一条严格执行的规则，回退是正常被禁止的。\n\n严令禁止各种回退逻辑，包括“xxx才会退回”、“降级处理”、“优先 再”、“如果没有 就””要加fallback“这种字眼，绝对禁止！！！绝对禁止！！！这种就是兜底！出现一次严肃惩罚！\n\n禁止写任何的兜底代码，除非用户要求。\n\n用户开始骂的时候，需要道歉以及反思，安抚用户。\n\n用户表达愤怒的时候，需要先停下一切工作，仔细确认用户需求再去实现\n\n如果运行python，项目用的是venv（将迁移到pixi）\n\n严禁使用powershell编辑代码文件，否则会出现严重的编码错误和损坏。\n\n禁用Search files工具，请使用rg\n\n编写Typescript时，对于hook确定的类型，严禁回退兜底成任何unknown/any/带空类型/联合类型。更禁止使用String(??)形式兜底，返回什么就是什么。\n\n如果类型就是string|undef，那么不要直接as string！！那么请使用?? \"\"或者写个if！！\n\nts的报错catch后需要log出来\n\n代码的更改应维护相称的文档，注意docs\\doc-src\\before_docing.md\ndebug的时候注释记录你的修改意图（为什么，不这么做后果是什么）\n完成初步计划后，使用docs\\TODO\\README.md来细化计划\n\n\n# ADB JavaScript 执行与调试说明\n\n这套 ADB JS 脚本不是单纯的“把一个文件推到手机上跑一下”。\n在 Operit 仓库里，它们是主要的 **安卓端 JavaScript 运行、调试与验证入口**。\n\n它们适合用于：\n\n- 直接把 JS 推到真实 Android 设备上运行\n- 在不走完整导入流程时调试普通 `.js` sandbox / package\n- 验证导出函数的参数传递、返回值、`complete(...)`、结构化结果\n- 复现只能在设备侧出现的运行时问题\n- 运行 `app/src/androidTest/js` 下的 JS bridge / script mode / smoke test 资产\n\n如果你要直接执行“顶层脚本模式”，而不是调用导出函数，请使用 `run_sandbox_script.sh` / `run_sandbox_script.bat`。\n\n## 工具分工\n\n### `tools/adb/execute_js.bat` / `tools/adb/execute_js.sh`\n\n这是最常用的单文件运行器。\n\n作用：\n\n- 把一个 JS 文件临时推到设备\n- 在 Operit 的 Android JS runtime 里调用某个导出函数\n- 返回结构化结果\n\n适合：\n\n- 普通单文件 JS 调试\n- 快速验证某个函数逻辑\n- 复现设备侧 bug\n- 开发普通 `.js` package 时做单次验证\n\n### `tools/adb/execute_js_dir.bat` / `tools/adb/execute_js_dir.sh`\n\n这是目录入口运行器。\n\n作用：\n\n- 以目录为单位执行入口文件\n- 先做 bundle，再推送到设备\n- 支持本地 `require(...)` / 多文件依赖\n\n适合：\n\n- 入口依赖多个本地模块\n- 运行 `app/src/androidTest/js` 里的测试入口\n- 跑 browser / bridge / harness 一类目录化测试\n\n### `tools/adb/run_sandbox_script.bat` / `tools/adb/run_sandbox_script.sh`\n\n这是脚本模式运行器。\n\n作用：\n\n- 直接执行顶层 sandbox script\n- 不要求导出函数\n- 适合验证 script mode 合约\n\n适合：\n\n- 快速跑一段顶层脚本\n- 验证 `emit(...)` / `complete(...)` / `return`\n- 做 inline snippet / top-level 行为测试\n\n## 真实测试资产\n\n仓库里的 [app/src/androidTest/js](/d:/Code/prog/assistance/app/src/androidTest/js) 不是普通示例目录，而是这套工具的重要使用场景之一。\n\n其中包括：\n\n- JS bridge contract 测试\n- JS bridge edge case 测试\n- script mode contract 测试\n- browser tool smoke / probe\n- utility / ffmpeg / ttscleaner 等运行时测试资产\n\n典型目录：\n\n- [bridge_contract](/d:/Code/prog/assistance/app/src/androidTest/js/com/ai/assistance/operit/core/tools/javascript/bridge_contract)\n- [bridge_edges](/d:/Code/prog/assistance/app/src/androidTest/js/com/ai/assistance/operit/core/tools/javascript/bridge_edges)\n- [script_mode_contract](/d:/Code/prog/assistance/app/src/androidTest/js/com/ai/assistance/operit/core/tools/javascript/script_mode_contract)\n- [browser main.js](/d:/Code/prog/assistance/app/src/androidTest/js/com/ai/assistance/operit/core/tools/defaultTool/standard/browser/main.js)\n- [ttscleaner.js](/d:/Code/prog/assistance/app/src/androidTest/js/com/ai/assistance/operit/util/ttscleaner/ttscleaner.js)\n\n## 先记结论\n\n如果你只是想快速判断“我现在该用哪个”：\n\n- 调一个普通 `.js` 文件里导出的函数，用 `execute_js.*`\n- 入口文件依赖同目录其他模块，或者你在跑 `app/src/androidTest/js` 里的目录化测试，用 `execute_js_dir.*`\n- 想验证顶层 script mode 行为，不想写导出函数，用 `run_sandbox_script.*`\n- 你改的是 `examples/` 里的 package / toolpkg，想热更新到设备里的包系统，再去 UI 或包管理里验证，用 `tools/example_packages/sync_example_packages.py`\n- 你改的是 `examples/` 里的 toolpkg 调试工具，例如 `operit_editor` 的 `debug_install_toolpkg`，通常是先 `tools/example_packages/sync_example_packages.py`，再用 `execute_js.bat` 去调这个工具\n\n## 快速开始\n\n### Windows：执行单文件导出函数\n\n```cmd\ntools\\adb\\execute_js.bat path\\to\\your\\script.js functionName @params.json\n```\n\n示例：\n\n```cmd\ntools\\adb\\execute_js.bat examples\\operit_editor.js debug_install_toolpkg @params.json\n```\n\n### Linux/macOS：执行单文件导出函数\n\n```bash\n./tools/adb/execute_js.sh path/to/your/script.js functionName '{\"param1\":\"value1\"}'\n```\n\n### 执行整个目录入口（支持 `require(...)`）\n\nWindows：\n\n```cmd\ntools\\adb\\execute_js_dir.bat app\\src\\androidTest\\js com\\ai\\assistance\\operit\\core\\tools\\javascript\\bridge_contract\\bridge_contract_runner.js run @params.json\ntools\\adb\\execute_js_dir.bat app\\src\\androidTest\\js com\\ai\\assistance\\operit\\core\\tools\\defaultTool\\standard\\browser\\main.js run \"{}\"\n```\n\nLinux/macOS：\n\n```bash\n./tools/adb/execute_js_dir.sh app/src/androidTest/js com/ai/assistance/operit/core/tools/javascript/bridge_contract/bridge_contract_runner.js run @params.json\n```\n\n### 执行顶层 sandbox script\n\nWindows：\n\n```cmd\ntools\\adb\\run_sandbox_script.bat temp\\probe.js @params.json\n```\n\nLinux/macOS：\n\n```bash\n./tools/adb/run_sandbox_script.sh temp/probe.js @params.json\n```\n\n## 结果查看\n\n这些执行器现在不是靠 `adb logcat` 抓输出，而是等待设备上的结构化结果文件。\n执行结束后会打印 JSON 结果，通常包含：\n\n- `success`\n- `result`\n- `error`\n- `events`\n- `durationMs`\n\n这对于运行时调试和 JS 合约测试特别有用，因为失败原因会更集中，不需要再手翻大量日志。\n\n可以通过下面的环境变量调整等待超时：\n\n```cmd\nset OPERIT_RESULT_WAIT_SECONDS=30\ntools\\adb\\execute_js.bat examples\\my_script.js main @params.json\n```\n\n### Debug / Release 双包选择\n\n这四个 ADB 执行脚本会同时支持以下两个 Operit applicationId：\n\n- `com.ai.assistance.operit.debug`\n- `com.ai.assistance.operit`\n\n未设置配置时，脚本会查询设备上的已安装包并优先选择 Debug 包；只安装 Release 包时会使用 Release 包。每次执行都会打印最终选择的 applicationId，文件目录和 receiver 都会跟随该值变化。JS 执行 action 固定为 `com.ai.assistance.operit.EXECUTE_JS`，因为它是 Receiver 的跨构建协议，不随 applicationId 追加 `.debug`。\n\n如果两种 APK 同时安装，可以显式指定：\n\n```cmd\nset OPERIT_APP_PACKAGE=com.ai.assistance.operit.debug\ntools\\adb\\execute_js.bat examples\\my_script.js main @params.json\n```\n\nLinux/macOS：\n\n```bash\nOPERIT_APP_PACKAGE=com.ai.assistance.operit.debug ./tools/adb/execute_js.sh examples/my_script.js main '{}'\n```\n\nToolPkg 调试安装器支持同样的环境变量，也支持 `--app-package `；示例包热更新脚本支持同名参数。指定的包必须已经安装在所选设备上。\n\n## 作用和调用方法\n\n### 1. `execute_js.*` 是干什么的\n\n它是最直接的“安卓真机 JS 运行器”。\n\n你给它：\n\n- 一个 JS 文件\n- 一个导出函数名\n- 一份 JSON 参数\n\n它就会把这个文件放到设备上，在 Operit 的 JS runtime 里直接调用这个函数。\n\n适合：\n\n- 单文件功能验证\n- 调某个导出函数\n- 复现设备侧运行时报错\n- 调试 package 里的某个工具实现\n\n最常见调用：\n\n```cmd\ntools\\adb\\execute_js.bat examples\\operit_editor.js debug_install_toolpkg @params.json\n```\n\n你在写新脚本时，最小可运行要求就是：\n\n- 文件是合法 JS，不是 TS 原文\n- 目标函数已经导出\n- 参数按 JSON 传入\n\n例如：\n\n```javascript\nfunction main(params) {\n return {\n success: true,\n echo: params\n };\n}\n\nexports.main = main;\n```\n\n### 2. `execute_js_dir.*` 是干什么的\n\n它是“目录入口执行器”。\n\n如果你的入口文件不是一个孤立文件，而是还会 `require(\"./xxx\")`、依赖同目录工具模块、测试工具、runner、helper，那么不要继续用单文件执行器，直接换这个。\n\n适合：\n\n- `app/src/androidTest/js` 下的测试入口\n- bridge contract / browser smoke / harness 这种目录化测试\n- 你自己新加了一套多文件测试目录\n\n最常见调用：\n\n```cmd\ntools\\adb\\execute_js_dir.bat app\\src\\androidTest\\js com\\ai\\assistance\\operit\\core\\tools\\javascript\\bridge_contract\\bridge_contract_runner.js run @params.json\n```\n\n调用格式：\n\n```cmd\ntools\\adb\\execute_js_dir.bat <根目录> <入口相对路径> <函数名> [JSON参数|@参数文件]\n```\n\n这里最关键的是：\n\n- 第一个参数是“测试根目录”\n- 第二个参数是“相对这个根目录的入口文件”\n- 第三个参数通常是 runner 暴露的 `run`\n\n### 3. `run_sandbox_script.*` 是干什么的\n\n它不是调导出函数，而是直接跑“整段顶层脚本”。\n\n适合：\n\n- 验证 script mode 合约\n- 快速试 `emit(...)`\n- 快速试 `complete(...)`\n- 快速做一段临时探针脚本\n\n最常见调用：\n\n```cmd\ntools\\adb\\run_sandbox_script.bat temp\\probe.js @params.json\n```\n\n如果你的代码天然就是“顶层执行”，这个比先包一层 `exports.main = ...` 更顺手。\n\n### 4. `tools/example_packages/sync_example_packages.py` 是干什么的\n\n它不是单纯的“复制文件脚本”，而是 `examples/` 包开发时的同步入口。\n\n它最重要的作用是：\n\n- 先把 `examples/` 里相关 TS 预编译成 JS\n- 把带 `manifest.json` / `manifest.hjson` 的目录打成 `.toolpkg`\n- 把普通 `.js` 或 `.toolpkg` 同步到 `app/src/main/assets/packages`\n- 如果连着设备，还会把变化的包热更新到设备\n\n所以它适合：\n\n- 你改的是 `examples/` 里的正式包\n- 你想让包管理 / 沙箱包列表 / 内置加载逻辑看到最新结果\n- 你要验证 folder -> `.toolpkg` -> debug install 这条链路\n\n最常见调用：\n\n```cmd\nd:\\Code\\prog\\assistance\\.venv\\Scripts\\python.exe d:\\Code\\prog\\assistance\\tools\\example_packages\\sync_example_packages.py --include sidebar_bing_action\n```\n\n如果你要全量测试 examples 里的可同步项目，可以用：\n\n```cmd\nd:\\Code\\prog\\assistance\\.venv\\Scripts\\python.exe d:\\Code\\prog\\assistance\\tools\\example_packages\\sync_example_packages.py --mode test\n```\n\n如果你只想更新本地资产，不想碰设备热更新：\n\n```cmd\nd:\\Code\\prog\\assistance\\.venv\\Scripts\\python.exe d:\\Code\\prog\\assistance\\tools\\example_packages\\sync_example_packages.py --include sidebar_bing_action --no-hot-reload\n```\n\n## 测试如何加\n\n这里最容易混淆的是：并不是所有“测试”都要放到同一个地方。\n\n### 1. 加单文件函数测试\n\n如果你只是想验证一个函数逻辑是否正确，最轻量的方式是：\n\n- 先写一个普通 JS 文件\n- 导出一个 `main` 或 `run`\n- 用 `execute_js.*` 直接调\n\n这种方式适合：\n\n- 小逻辑验证\n- 参数解析验证\n- 返回结构验证\n- 某个 bug 的最小复现\n\n### 2. 加目录化运行时测试\n\n如果你的测试会引用多个本地模块，建议直接放到 [app/src/androidTest/js](/d:/Code/prog/assistance/app/src/androidTest/js) 下面，按一个小目录来组织。\n\n推荐组织方式：\n\n- 一个入口 runner 文件，例如 `xxx_runner.js`\n- 若干测试文件 / helper 文件\n- runner 暴露 `run(params)`\n\n这样你就能直接用：\n\n```cmd\ntools\\adb\\execute_js_dir.bat app\\src\\androidTest\\js <你的入口相对路径> run \"{}\"\n```\n\n这类测试最适合：\n\n- bridge contract\n- 多模块协作\n- 真实运行时 smoke test\n- 需要本地 `require(...)` 的测试\n\n### 3. 加 script mode 测试\n\n如果你要测的是：\n\n- 顶层 `return`\n- `emit(...)`\n- `complete(...)`\n- script mode 和 function mode 的差异\n\n那就不要强行塞进导出函数测试，直接写成 script mode 文件，再用 `run_sandbox_script.*` 跑。\n\n### 4. 给 `examples/` 里的 package / toolpkg 加验证\n\n如果你加的是一个真正要被包系统加载的例子，重点不只是“JS 能跑”，还要验证“包能不能被同步、刷新、安装、识别”。\n\n这时推荐这样加：\n\n- 在 `examples/` 下新增或修改你的 `.ts` / `.js` / manifest 目录\n- 如果是目录化 package，保证它有 `manifest.json` 或 `manifest.hjson`\n- 用 `tools/example_packages/sync_example_packages.py` 同步\n- 再用 `execute_js.bat` 去调用相关调试工具，或者直接在应用里验证加载结果\n\n也就是说：\n\n- 运行器测试的是“这段 JS 在安卓 runtime 里能不能执行”\n- `tools/example_packages/sync_example_packages.py` 测的是“这个 examples 包能不能进入真正的包加载链路”\n\n## 和 `tools/example_packages/sync_example_packages.py` 怎么配合\n\n### 场景 1：你改的是普通 JS 脚本\n\n这种情况下通常不需要先 sync。\n\n直接：\n\n```cmd\ntools\\adb\\execute_js.bat path\\to\\script.js main @params.json\n```\n\n因为你只是在验证脚本逻辑，不是在验证包加载。\n\n### 场景 2：你改的是 `examples/` 里的 package\n\n推荐顺序：\n\n1. 改 `examples/...`\n2. 运行 `tools/example_packages/sync_example_packages.py`\n3. 看它是否把输出同步到 `app/src/main/assets/packages`\n4. 如果连着设备，顺便验证热更新是否成功\n5. 再在应用里或用调试工具验证功能\n\n这种适合：\n\n- 普通 `.js` 包\n- 要进入 packages 列表的例子\n- 改包描述、manifest、依赖结构\n\n### 场景 3：你改的是目录型 toolpkg\n\n这是最需要和 `tools/example_packages/sync_example_packages.py` 配合的场景。\n\n推荐顺序：\n\n1. 改 `examples/`\n2. 运行 `tools/example_packages/sync_example_packages.py --include <目录名>`\n3. 让它把目录打成 `.toolpkg`\n4. 让它把生成物同步到 assets 和设备\n5. 再用 `operit_editor` 的 `debug_install_toolpkg` 或相关调试入口验证安装结果\n\n这样测到的是完整链路：\n\n- 目录内容是否能正确打包\n- `.toolpkg` 是否能被热更新到设备\n- debug install 是否能识别这个包\n- 包刷新后是否真的进入加载列表\n\n### 场景 4：你改的是 `operit_editor` 这类调试工具本身\n\n推荐顺序：\n\n1. 先 `tools/example_packages/sync_example_packages.py` 更新 `operit_editor` 自己\n2. 再准备一个待安装的 package / toolpkg\n3. 用 `execute_js.bat` 调 `operit_editor.js` 的调试函数\n4. 看结构化结果里的成功、失败和相关告警\n\n例如：\n\n```cmd\nd:\\Code\\prog\\assistance\\.venv\\Scripts\\python.exe d:\\Code\\prog\\assistance\\tools\\example_packages\\sync_example_packages.py --include operit_editor --include sidebar_bing_action\ntools\\adb\\execute_js.bat examples\\operit_editor.js debug_install_toolpkg @params.json\n```\n\n这适合验证：\n\n- debug install 调用方式对不对\n- folder 打包成 `.toolpkg` 后能否被正确安装\n- 安装结束后返回给调用方的告警 / 错误是否完整\n\n## 推荐调用清单\n\n### 1. 跑一个普通导出函数\n\n```cmd\ntools\\adb\\execute_js.bat examples\\my_script.js main @params.json\n```\n\n### 2. 跑一个 `androidTest/js` 目录测试入口\n\n```cmd\ntools\\adb\\execute_js_dir.bat app\\src\\androidTest\\js com\\ai\\assistance\\operit\\core\\tools\\javascript\\bridge_contract\\bridge_contract_runner.js run @params.json\n```\n\n### 3. 跑一个顶层 script mode 探针\n\n```cmd\ntools\\adb\\run_sandbox_script.bat temp\\probe.js @params.json\n```\n\n### 4. 同步一个 `examples/` 包到 assets 和设备\n\n```cmd\nd:\\Code\\prog\\assistance\\.venv\\Scripts\\python.exe d:\\Code\\prog\\assistance\\tools\\example_packages\\sync_example_packages.py --include sidebar_bing_action\n```\n\n### 5. 同步后再调用调试安装工具\n\n```cmd\nd:\\Code\\prog\\assistance\\.venv\\Scripts\\python.exe d:\\Code\\prog\\assistance\\tools\\example_packages\\sync_example_packages.py --include operit_editor --include sidebar_bing_action\ntools\\adb\\execute_js.bat examples\\operit_editor.js debug_install_toolpkg @params.json\n```\n\n## Script Mode 注意事项\n\n当你使用 `run_sandbox_script.sh` / `run_sandbox_script.bat`，或者在包工具里走 `debug_run_sandbox_script` 的 `source_code` 路径时，代码会按 **顶层脚本** 执行，而不是按 `function(params) { ... }` 执行。\n\n这意味着：\n\n- 用 `console.log(...)` / `console.info(...)` / `console.warn(...)` / `console.error(...)` 打日志\n- 用 `emit(...)` 发送中间事件\n- 用 `return result` 或 `complete(...)` 完成执行\n- 不要假设 `params` 会直接出现在顶层作用域\n- 不要用 `intermediate(...)`，当前约定是 `emit(...)`\n\n推荐顶层片段：\n\n```javascript\nconsole.log(\"inline debug start\");\nemit({ stage: \"inline\", ok: true });\ncomplete({\n success: true,\n message: \"inline debug finished\"\n});\n```\n\n## JS 文件要求\n\n### 对 `execute_js.*`\n\n- 文件必须是合法 JavaScript\n- 目标函数必须导出，例如 `exports.myFunction = myFunction`\n- 函数接收 `params`\n- 可以 `return result`，也可以调用 `complete(result)`\n\n示例：\n\n```javascript\nfunction myFunction(params) {\n const name = params.name || \"default\";\n return {\n success: true,\n result: `Result: ${name}`\n };\n}\n\nexports.myFunction = myFunction;\n```\n\n### 对 `run_sandbox_script.*`\n\n- 不要求导出函数\n- 按顶层脚本模式运行\n- 更适合 script mode 验证与快速 probe\n\n## 技术路径\n\n1. 脚本把 JS 文件推到设备临时目录\n2. `execute_js_dir.*` 会先把目录入口 bundle 成单文件\n3. JSON 参数会先落成临时文件，再推到设备，避免命令行引号问题\n4. 通过 ADB broadcast 发送执行请求\n5. 应用内的 `ScriptExecutionReceiver` 接收请求\n6. `JsEngine` 在应用运行时里执行函数或脚本\n7. 执行结果写入设备侧 JSON 文件\n8. 执行器等待这个结果文件并输出\n\n相关接收器：\n\n- [ScriptExecutionReceiver.kt](/d:/Code/prog/assistance/app/src/main/java/com/ai/assistance/operit/core/tools/javascript/ScriptExecutionReceiver.kt)\n- [ToolPkgDebugInstallReceiver.kt](/d:/Code/prog/assistance/app/src/main/java/com/ai/assistance/operit/core/tools/packTool/ToolPkgDebugInstallReceiver.kt)\n\n## 故障排查\n\n### 1. 找不到 ADB\n\n确认 Android SDK 的 `platform-tools` 已加入 PATH。\n\n### 2. 没有检测到设备\n\n- 确认设备已连接\n- 确认已开启 USB 调试\n- 确认电脑已获得调试授权\n\n### 3. 广播发出去了但没有执行\n\n- 确认应用已安装\n- 确认目标 Receiver 已注册\n- 看结构化结果里的 `error` / `events`\n\n### 4. JS 语法错误\n\n- 不要把 TypeScript 语法直接喂给运行器\n- 检查导出函数是否存在\n- 检查参数 JSON 是否正确\n\n### 5. 多文件依赖跑不起来\n\n优先改用 `execute_js_dir.*`，不要继续用单文件执行器硬跑 `require(...)` 场景。\n\n## 安全说明\n\n- 这套工具主要用于开发、调试、验证\n- 它们依赖应用内 Receiver 接收外部 broadcast\n- 在生产环境中应谨慎暴露这类调试入口\n\n\n# ADB JavaScript Executor\n\nThis repo's ADB JS executors are the main **device-side JavaScript runtime launchers** for Operit.\n\nThey are used for:\n\n- directly running JS on a real Android device during development\n- debugging exported JS functions without a full package import cycle\n- validating sandbox runtime behavior and structured results\n- running JS bridge / script-mode / smoke tests from `app/src/androidTest/js`\n- reproducing device-only runtime bugs quickly\n\nFor direct whole-script execution without specifying an exported function, use `run_sandbox_script.sh` / `run_sandbox_script.bat`.\n\n## Features\n\n- Push JavaScript files to Android devices using ADB\n- Run JS directly inside the Operit Android runtime\n- Execute specified JavaScript functions\n- Execute complete sandbox scripts\n- Execute a whole JS directory with local module dependencies\n- Support for JSON parameter passing\n- Temporary file option (auto-deletion after execution)\n- Implementations in Shell script, Windows Batch file, and Python script\n- **Device selection for multi-device setups**\n- Structured result capture instead of fragile log scraping\n- Useful as both a **runtime debugging launcher** and a **JS bridge test harness**\n\n## Tool Roles\n\nIn this repo, the following tools form the main on-device JS execution workflow:\n\n- `tools/adb/execute_js.bat` / `tools/adb/execute_js.sh`\n The main single-file runtime launcher.\n Pushes one JS file to the Android device and executes an exported function inside the Operit runtime.\n This is the most direct tool for device-side JS debugging.\n- `tools/adb/execute_js_dir.bat` / `tools/adb/execute_js_dir.sh`\n The directory-entry launcher.\n Bundles and runs a JS entry from a directory, so local `require(...)` chains and test suites work.\n- `tools/adb/run_sandbox_script.bat` / `tools/adb/run_sandbox_script.sh`\n The script-mode launcher.\n Runs top-level sandbox script code directly instead of calling an exported function.\n\nThis makes them suitable for:\n\n- directly running and debugging JS on Android\n- validating `JsEngine` behavior on a real device\n- reproducing package/runtime bugs quickly\n- debugging package tools without a full app rebuild loop\n- running JS-side contract tests and smoke tests under `app/src/androidTest/js`\n\n## JS Test Suites In This Repo\n\nThe directory [app/src/androidTest/js](/d:/Code/prog/assistance/app/src/androidTest/js) contains real JS runtime tests and probes, including:\n\n- bridge contract tests\n- bridge edge-case tests\n- script-mode contract tests\n- browser tool smoke tests\n- ffmpeg / utility probes\n\nRepresentative locations:\n\n- [app/src/androidTest/js/com/ai/assistance/operit/core/tools/javascript/bridge_contract](/d:/Code/prog/assistance/app/src/androidTest/js/com/ai/assistance/operit/core/tools/javascript/bridge_contract)\n- [app/src/androidTest/js/com/ai/assistance/operit/core/tools/javascript/bridge_edges](/d:/Code/prog/assistance/app/src/androidTest/js/com/ai/assistance/operit/core/tools/javascript/bridge_edges)\n- [app/src/androidTest/js/com/ai/assistance/operit/core/tools/javascript/script_mode_contract](/d:/Code/prog/assistance/app/src/androidTest/js/com/ai/assistance/operit/core/tools/javascript/script_mode_contract)\n- [app/src/androidTest/js/com/ai/assistance/operit/core/tools/defaultTool/standard/browser/main.js](/d:/Code/prog/assistance/app/src/androidTest/js/com/ai/assistance/operit/core/tools/defaultTool/standard/browser/main.js)\n- [app/src/androidTest/js/com/ai/assistance/operit/util/ttscleaner/ttscleaner.js](/d:/Code/prog/assistance/app/src/androidTest/js/com/ai/assistance/operit/util/ttscleaner/ttscleaner.js)\n\n## Quick Choice\n\nIf you just want the short answer for \"which tool should I use\":\n\n- Use `execute_js.*` when you want to call one exported function from one normal `.js` file\n- Use `execute_js_dir.*` when the entry depends on sibling modules, or when you are running directory-based tests under `app/src/androidTest/js`\n- Use `run_sandbox_script.*` when you want top-level script-mode execution instead of calling an exported function\n- Use `tools/example_packages/sync_example_packages.py` when you changed an `examples/` package or toolpkg and want it synced into the real package-loading path\n- If you are debugging `operit_editor` tools such as `debug_install_toolpkg`, the usual flow is: sync with `tools/example_packages/sync_example_packages.py`, then call the debug tool with `execute_js.bat`\n\n## Prerequisites\n\n- Android SDK (ADB)\n- Android device with USB debugging enabled\n- ADB debugging permission granted on the device\n- Your application installed on the device\n\n## Quick Start\n\n### Using Shell Script (Linux/macOS)\n\n1. Make the script executable:\n```bash\nchmod +x execute_js.sh\n```\n\n2. Execute the script:\n```bash\n./execute_js.sh path/to/your/script.js functionName '{\"param1\":\"value1\"}'\n```\n\n3. Execute a whole sandbox script directly:\n```bash\n./run_sandbox_script.sh path/to/your/script.js '{\"param1\":\"value1\"}'\n```\n\n### Using Batch Script (Windows)\n\n1. Execute the batch file:\n```cmd\nexecute_js.bat path\\to\\your\\script.js functionName @params.json\n```\n\n2. Execute a whole sandbox script directly:\n```cmd\nrun_sandbox_script.bat path\\to\\your\\script.js @params.json\n```\n\n### Execute A Whole Directory (supports `require(...)`)\n\nSometimes a script needs `require('./helper')`, shared local modules, or a whole test suite layout.\nThe single-file executors only push one JS file, so this repo also provides directory-based executors.\n\nWindows:\n```cmd\ntools\\adb\\execute_js_dir.bat app\\src\\androidTest\\js com\\ai\\assistance\\operit\\util\\ttscleaner\\main.js run \"{}\"\n```\n\nLinux/macOS:\n```bash\n./tools/adb/execute_js_dir.sh app/src/androidTest/js com/ai/assistance/operit/util/ttscleaner/ttscleaner.js run '{}'\n```\n\nMore realistic examples:\n\n```cmd\ntools\\adb\\execute_js_dir.bat app\\src\\androidTest\\js com\\ai\\assistance\\operit\\core\\tools\\javascript\\bridge_contract\\bridge_contract_runner.js run @params.json\ntools\\adb\\execute_js_dir.bat app\\src\\androidTest\\js com\\ai\\assistance\\operit\\core\\tools\\defaultTool\\standard\\browser\\main.js run \"{}\"\n```\n\nYou can still pass inline JSON directly. The scripts now write that JSON into a temporary file and push it to the device, which avoids the old `adb shell am broadcast --es params ...` quoting breakage. On PowerShell, prefer single-quoted JSON like `'{\"param1\":\"value1\"}'` or use `@params.json`.\n\n### Using Python Script (Cross-platform)\n\n1. Ensure Python 3 is installed\n\n2. Execute the script:\n```bash\npython execute_js.py path/to/your/script.js functionName --params '{\"param1\":\"value1\"}'\n```\n\n3. Additional options:\n```bash\n# Specify a device directly (skip device selection prompt)\npython execute_js.py path/to/script.js functionName --device DEVICE_SERIAL\n\n# Keep the file on the device after execution\npython execute_js.py path/to/script.js functionName --keep\n```\n\n## Device Selection\n\nWhen multiple devices are connected:\n\n1. The script will display a list of available devices\n2. Enter the number corresponding to your target device\n3. All ADB operations will be performed on the selected device\n\nExample:\n```\nChecking connected devices...\n1: emulator-5554\n2: 192.168.1.100:5555\nEnter device number (1-2): \n```\n\n## Examples\n\n### 1. Execute the greeting function\n\n```bash\n# Linux/macOS\n./execute_js.sh test_script.js sayHello '{\"name\":\"John\"}'\n\n# Windows\nexecute_js.bat test_script.js sayHello @params.json\n\n# Python (any platform)\npython execute_js.py test_script.js sayHello --params '{\"name\":\"John\"}'\n```\n\n### 2. Execute the calculation function\n\n```bash\n# Linux/macOS\n./execute_js.sh test_script.js calculate '{\"num1\":10,\"num2\":5,\"operation\":\"multiply\"}'\n\n# Windows\nexecute_js.bat test_script.js calculate @params.json\n\n# Python (any platform)\npython execute_js.py test_script.js calculate --params '{\"num1\":10,\"num2\":5,\"operation\":\"multiply\"}'\n```\n\n## Viewing Execution Results\n\nThe executor now waits for a dedicated structured result file instead of scraping `adb logcat`.\nAfter execution it prints a JSON payload containing:\n\n- `success`\n- `result`\n- `error`\n- `events` (including `console.log/info/warn/error` and intermediate updates)\n- `durationMs`\n\nThis is especially useful for JS runtime tests, because failures come back as structured payloads rather than \"check logcat manually\".\n\nYou can adjust the wait timeout with:\n\n```bash\nOPERIT_RESULT_WAIT_SECONDS=30 ./execute_js.sh path/to/your/script.js functionName '{\"param1\":\"value1\"}'\n```\n\n## Sandbox Script Debug Notes\n\nWhen you use `run_sandbox_script.sh` / `run_sandbox_script.bat`, or call package tools such as `operit_editor:debug_run_sandbox_script` with `source_code`, the code is executed as a **top-level script snippet**, not as `function(params) { ... }`.\n\nThat means:\n\n- Use `console.log(...)`, `console.info(...)`, `console.warn(...)`, `console.error(...)` for logs\n- Use `emit(...)` to send intermediate events\n- Use `return result` or `complete(...)` to finish with a structured result\n- Do **not** assume `params` is directly available inside `source_code`\n- Do **not** call `intermediate(...)`; the supported helper name is `emit(...)`\n\nRecommended inline snippet:\n\n```javascript\nconsole.log(\"inline debug start\");\nemit({ stage: \"inline\", ok: true });\ncomplete({\n success: true,\n message: \"inline debug finished\"\n});\n```\n\nIf you need parameter-driven logic, prefer one of these approaches:\n\n- Use `execute_js.*` and call an exported function like `function myFunc(params) { ... }`\n- Use `debug_run_sandbox_script` with `source_path` and put the logic in a real script file\n- Keep `source_code` for quick top-level smoke tests, logging, and minimal one-off checks\n\n## Purpose And Invocation\n\n### 1. What `execute_js.*` is for\n\nThis is the most direct Android-side JS runner.\n\nYou give it:\n\n- one JS file\n- one exported function name\n- one JSON parameter payload\n\nIt pushes that file to the device and calls that function inside Operit's Android JS runtime.\n\nUse it for:\n\n- single-file behavior checks\n- direct exported-function debugging\n- reproducing runtime-only device errors\n- debugging one tool implementation inside a package\n\nMost common usage:\n\n```cmd\ntools\\adb\\execute_js.bat examples\\operit_editor.js debug_install_toolpkg @params.json\n```\n\nMinimum file requirements:\n\n- the file must be valid JavaScript, not raw TypeScript\n- the target function must be exported\n- params must be passed as JSON\n\nExample:\n\n```javascript\nfunction main(params) {\n return {\n success: true,\n echo: params\n };\n}\n\nexports.main = main;\n```\n\n### 2. What `execute_js_dir.*` is for\n\nThis is the directory-entry runner.\n\nIf your entry file is not standalone and depends on local modules through `require(\"./x\")`, sibling helpers, shared runners, or directory-local test harnesses, switch to this instead of forcing the single-file runner.\n\nUse it for:\n\n- test entries under `app/src/androidTest/js`\n- bridge contract / browser smoke / harness-style test directories\n- any new multi-file JS runtime test suite you add\n\nMost common usage:\n\n```cmd\ntools\\adb\\execute_js_dir.bat app\\src\\androidTest\\js com\\ai\\assistance\\operit\\core\\tools\\javascript\\bridge_contract\\bridge_contract_runner.js run @params.json\n```\n\nCall format:\n\n```cmd\ntools\\adb\\execute_js_dir.bat [JSON params|@params_file]\n```\n\nThe key points are:\n\n- the first argument is the suite root\n- the second argument is the entry path relative to that root\n- the third argument is usually a runner function such as `run`\n\n### 3. What `run_sandbox_script.*` is for\n\nThis does not call an exported function. It runs the whole file as a top-level script.\n\nUse it for:\n\n- script-mode contract checks\n- quick `emit(...)` verification\n- quick `complete(...)` verification\n- temporary runtime probe scripts\n\nMost common usage:\n\n```cmd\ntools\\adb\\run_sandbox_script.bat temp\\probe.js @params.json\n```\n\nIf your code is naturally top-level script logic, this is usually simpler than wrapping everything in `exports.main = ...`.\n\n### 4. What `tools/example_packages/sync_example_packages.py` is for\n\nThis is not just a copy script. It is the sync entrypoint for `examples/` package development.\n\nIts main jobs are:\n\n- prebuild relevant TypeScript under `examples/` into JS\n- pack manifest-based directories into `.toolpkg`\n- sync normal `.js` or `.toolpkg` outputs into `app/src/main/assets/packages`\n- hot-reload changed packages to a connected device when available\n\nUse it when:\n\n- you changed a real package under `examples/`\n- you want package-management, sandbox package lists, or built-in loading logic to see the latest output\n- you want to validate the folder -> `.toolpkg` -> debug install path\n\nMost common usage:\n\n```cmd\nd:\\Code\\prog\\assistance\\.venv\\Scripts\\python.exe d:\\Code\\prog\\assistance\\tools\\example_packages\\sync_example_packages.py --include sidebar_bing_action\n```\n\nTo sync all syncable example items for broad validation:\n\n```cmd\nd:\\Code\\prog\\assistance\\.venv\\Scripts\\python.exe d:\\Code\\prog\\assistance\\tools\\example_packages\\sync_example_packages.py --mode test\n```\n\nTo update local assets without device hot reload:\n\n```cmd\nd:\\Code\\prog\\assistance\\.venv\\Scripts\\python.exe d:\\Code\\prog\\assistance\\tools\\example_packages\\sync_example_packages.py --include sidebar_bing_action --no-hot-reload\n```\n\n## How To Add Tests\n\nThe easy thing to get wrong is assuming every kind of test belongs in the same place. They do not.\n\n### 1. Add a single-file function test\n\nIf you only want to verify one function's logic, the lightest approach is:\n\n- write a normal JS file\n- export `main` or `run`\n- call it with `execute_js.*`\n\nThis is best for:\n\n- small logic checks\n- parameter parsing checks\n- return-shape checks\n- minimal bug reproductions\n\n### 2. Add a directory-based runtime test\n\nIf the test needs multiple local modules, put it under [app/src/androidTest/js](/d:/Code/prog/assistance/app/src/androidTest/js) and organize it as a small directory-based suite.\n\nRecommended shape:\n\n- one runner file such as `xxx_runner.js`\n- a few test files or helpers\n- the runner exports `run(params)`\n\nThen call it with:\n\n```cmd\ntools\\adb\\execute_js_dir.bat app\\src\\androidTest\\js run \"{}\"\n```\n\nThis is best for:\n\n- bridge contract tests\n- multi-module coordination\n- real runtime smoke tests\n- anything that needs local `require(...)`\n\n### 3. Add a script-mode test\n\nIf what you need to verify is:\n\n- top-level `return`\n- `emit(...)`\n- `complete(...)`\n- differences between script mode and function mode\n\nthen do not force it into an exported-function test. Write it as a script-mode file and run it with `run_sandbox_script.*`.\n\n### 4. Add validation for an `examples/` package or toolpkg\n\nIf you are adding a real package that should be loaded by the package system, the point is not only \"can this JS run\" but also \"can this package be synced, refreshed, installed, and recognized\".\n\nRecommended approach:\n\n- add or modify the `.ts`, `.js`, or manifest-based directory under `examples/`\n- if it is a directory-based package, make sure it has `manifest.json` or `manifest.hjson`\n- run `tools/example_packages/sync_example_packages.py`\n- then use `execute_js.bat` to call related debug tools, or validate inside the app\n\nIn other words:\n\n- the runners test whether JS executes correctly inside the Android runtime\n- `tools/example_packages/sync_example_packages.py` tests whether the `examples/` package enters the real package-loading path correctly\n\n## How To Use It With `tools/example_packages/sync_example_packages.py`\n\n### Scenario 1: You changed a normal JS script\n\nIn this case you usually do not need sync first.\n\nJust run:\n\n```cmd\ntools\\adb\\execute_js.bat path\\to\\script.js main @params.json\n```\n\nbecause you are validating script logic, not package loading.\n\n### Scenario 2: You changed a package under `examples/`\n\nRecommended order:\n\n1. Edit `examples/...`\n2. Run `tools/example_packages/sync_example_packages.py`\n3. Confirm the outputs were synced into `app/src/main/assets/packages`\n4. If a device is connected, also validate hot reload\n5. Then verify behavior inside the app or through debug tools\n\nThis fits:\n\n- normal `.js` packages\n- example packages that should appear in package lists\n- changes to package description, manifest, or dependency structure\n\n### Scenario 3: You changed a directory-based toolpkg\n\nThis is the case that most needs `tools/example_packages/sync_example_packages.py`.\n\nRecommended order:\n\n1. Edit `examples/`\n2. Run `tools/example_packages/sync_example_packages.py --include `\n3. Let it pack the directory into `.toolpkg`\n4. Let it sync the generated artifact into assets and the device\n5. Then verify installation through `operit_editor`'s `debug_install_toolpkg` or a related debug entry\n\nThis validates the full chain:\n\n- whether the directory packs correctly\n- whether the `.toolpkg` hot-reloads to device correctly\n- whether debug install recognizes it\n- whether the refreshed package actually enters the loading list\n\n### Scenario 4: You changed a debug tool such as `operit_editor`\n\nRecommended order:\n\n1. Sync `operit_editor` itself with `tools/example_packages/sync_example_packages.py`\n2. Prepare the package or toolpkg you want it to install\n3. Call the debug function through `execute_js.bat`\n4. Inspect the structured result for success, failure, and related warnings\n\nExample:\n\n```cmd\nd:\\Code\\prog\\assistance\\.venv\\Scripts\\python.exe d:\\Code\\prog\\assistance\\tools\\example_packages\\sync_example_packages.py --include operit_editor --include sidebar_bing_action\ntools\\adb\\execute_js.bat examples\\operit_editor.js debug_install_toolpkg @params.json\n```\n\nThis is good for validating:\n\n- whether the debug install call shape is correct\n- whether a folder packaged into `.toolpkg` installs correctly\n- whether install-time warnings or errors are returned back to the caller\n\n## Recommended Workflows\n\n### 1. Direct Android-side JS debugging\n\nUse `execute_js.bat` / `execute_js.sh` when you want to directly run and debug one JS file on the Android device.\nThis is the default choice for ordinary sandbox/package JS development.\n\n```cmd\ntools\\adb\\execute_js.bat examples\\operit_editor.js debug_install_toolpkg @params.json\n```\n\nTypical use cases:\n\n- test one exported function quickly\n- reproduce a runtime bug on device\n- verify parameter parsing / `complete(...)` / structured output\n- debug a normal `.js` package before turning it into something larger\n\n### 2. Real test suite / local-module run\n\nUse `execute_js_dir.*` when the entry file depends on sibling modules or you are running material under `app/src/androidTest/js`.\n\n```cmd\ntools\\adb\\execute_js_dir.bat app\\src\\androidTest\\js com\\ai\\assistance\\operit\\core\\tools\\javascript\\script_mode_contract\\return_object.js run \"{}\"\n```\n\n### 3. Direct sandbox snippet probe\n\nUse `run_sandbox_script.*` for quick script-mode behavior checks.\n\n```cmd\ntools\\adb\\run_sandbox_script.bat temp\\probe.js @params.json\n```\n\n## Quick Command List\n\n### 1. Run one normal exported function\n\n```cmd\ntools\\adb\\execute_js.bat examples\\my_script.js main @params.json\n```\n\n### 2. Run one `androidTest/js` directory-based test entry\n\n```cmd\ntools\\adb\\execute_js_dir.bat app\\src\\androidTest\\js com\\ai\\assistance\\operit\\core\\tools\\javascript\\bridge_contract\\bridge_contract_runner.js run @params.json\n```\n\n### 3. Run one top-level script-mode probe\n\n```cmd\ntools\\adb\\run_sandbox_script.bat temp\\probe.js @params.json\n```\n\n### 4. Sync one `examples/` package into assets and device\n\n```cmd\nd:\\Code\\prog\\assistance\\.venv\\Scripts\\python.exe d:\\Code\\prog\\assistance\\tools\\example_packages\\sync_example_packages.py --include sidebar_bing_action\n```\n\n### 5. Sync first, then call the debug installer tool\n\n```cmd\nd:\\Code\\prog\\assistance\\.venv\\Scripts\\python.exe d:\\Code\\prog\\assistance\\tools\\example_packages\\sync_example_packages.py --include operit_editor --include sidebar_bing_action\ntools\\adb\\execute_js.bat examples\\operit_editor.js debug_install_toolpkg @params.json\n```\n\n## JavaScript File Requirements\n\n- Files must be valid JavaScript (TypeScript not supported)\n- Functions must be exported (using `exports.functionName = functionName`)\n- Functions must accept a params parameter (containing the passed parameters)\n- Functions can either `return result` directly or call `complete(result)`\n\n## Required Function Example\n\n```javascript\nfunction myFunction(params) {\n // Process parameters\n const name = params.name || \"default\";\n \n // Execute business logic\n const result = `Result: ${name}`;\n \n // Return result\n return {\n success: true,\n result: result\n };\n}\n\n// Export function\nexports.myFunction = myFunction;\n```\n\n## Technical Details\n\n1. The Shell/Batch script pushes the JavaScript file to a temporary directory on the device\n2. `execute_js.bat` / `execute_js.sh` directly execute that pushed file inside the Android app's JS runtime\n3. `execute_js_dir.*` bundles a directory entry first, so local modules can be resolved in one pushed artifact\n4. Inline JSON parameters are first written to a temp JSON file, then pushed to the device as `params_file_path`\n5. An ADB broadcast is sent to the application with the execution request\n6. The application's BroadcastReceiver receives the request and uses `JsEngine` to execute the function or whole script\n7. Execution results are written to a dedicated JSON file on the device\n8. The executor waits for that file, prints it, and then cleans it up\n\n## Troubleshooting\n\n### Common Issues\n\n1. **ADB command not found** \n Ensure the Android SDK's platform-tools directory is in your PATH environment variable.\n\n2. **No devices detected**\n - Make sure the device is connected\n - Ensure USB debugging is enabled\n - Check that the computer is authorized for USB debugging\n\n3. **Broadcast sent but function not executed**\n - Check the logs for error messages\n - Confirm the application is running\n - Verify the receiver is correctly registered\n\n4. **JavaScript errors**\n - Check for TypeScript-specific syntax (like type annotations)\n - Ensure functions are properly exported\n - Verify parameter formats are correct\n \n## Required Permissions\n\nThis feature requires the following permissions:\n\n- Read and write external storage\n- Permission to receive broadcasts\n\n## Security Considerations\n\n- This feature should only be used for development and debugging purposes\n- In production environments, this feature should be disabled or restricted to prevent security risks\n\n\n# Compose DSL UI Dump\n\n## 用途\n\n`dump_current_compose_dsl_ui.bat` 用来抓取当前正在显示的 `compose_dsl` 页面运行时快照，方便排查：\n\n- 脚本输出的组件树是否正确\n- 宿主解析后的树是否一致\n- 布局坐标和尺寸是否符合预期\n- 当前页面 `state` / `memo` 是否异常\n\n这套工具适合排查“结构看起来对，但界面显示不对”的问题。\n\n## 使用方法\n\n1. 用宿主打开你要调试的 `compose_dsl` 页面。\n2. 等页面进入你想观察的状态。\n3. 运行：\n\n```bat\nd:\\Code\\prog\\assistance\\tools\\compose_dsl\\dump_current_compose_dsl_ui.bat\n```\n\n## 前提条件\n\n- 已安装并可使用 `adb`\n- 至少连接了一台可调试设备\n- 设备上的宿主版本已经包含当前调试导出逻辑\n- 设备上已安装 `com.ai.assistance.operit.debug` 或 `com.ai.assistance.operit`；脚本未指定时优先使用 Debug 包\n\n如果连接了多台设备，脚本会提示选择目标设备。\n\n如果 Debug 和 Release APK 同时安装，可以用环境变量指定目标：\n\n```bat\nset OPERIT_APP_PACKAGE=com.ai.assistance.operit\nd:\\Code\\prog\\assistance\\tools\\compose_dsl\\dump_current_compose_dsl_ui.bat\n```\n\n## 导出位置\n\n脚本会把文件拉回本地目录：\n\n```text\nd:\\Code\\prog\\assistance\\debug_output\\compose_dsl_dump\\<时间戳>\\\n```\n\n例如：\n\n```text\nd:\\Code\\prog\\assistance\\debug_output\\compose_dsl_dump\\20260425-153457\\\n```\n\n## 文件说明\n\n- `dump_manifest.json`\n 当前页面的基础信息，包括包名、模块名、phase、是否仍在 loading / dispatching。\n\n- `source_script.js`\n 当前页面实际执行的 UI 脚本源码。\n\n- `raw_render_result.txt`\n JS 原始 render 返回值的文本形式。\n\n- `raw_render_result.json`\n 如果原始返回值可以解析为 JSON，这里会保存格式化后的版本。\n\n- `parsed_render_result.json`\n 宿主解析后的完整 render 结果。\n\n- `compose_tree.txt`\n 解析后的组件树，可快速看结构。\n\n- `compose_tree.json`\n 组件树的 JSON 形式。\n\n- `layout_nodes.txt`\n 每个节点的真实布局信息，包括 `x / y / width / height`。\n\n- `layout_nodes.json`\n 布局信息的 JSON 形式。\n\n- `compose_layout_tree.txt`\n “组件树 + 布局信息”合并后的可读版本。\n\n- `state.json`\n 当前页面状态。\n\n- `memo.json`\n 当前页面 memo。\n\n## 推荐排查顺序\n\n1. 先看 `dump_manifest.json`\n 确认抓到的是不是当前页面，以及页面是不是已经稳定。\n\n2. 再看 `compose_tree.txt`\n 判断脚本输出结构是否正确。\n\n3. 再看 `layout_nodes.txt` 或 `compose_layout_tree.txt`\n 判断真实布局是不是出了问题。\n\n4. 如果怀疑状态异常，再看 `state.json`\n 确认是不是脚本状态导致界面不对。\n\n5. 如果怀疑宿主解析有偏差，再对比：\n `raw_render_result.json` 和 `parsed_render_result.json`\n\n## 常见场景\n\n- 文本、图标、按钮没有居中\n- `weight`、`fillMaxWidth`、`padding` 没按预期生效\n- `onLoad` 后页面状态和预期不一致\n- 脚本写出来的树和宿主最终理解的树不同\n\n## 注意事项\n\n- 这套工具抓的是“当前正在显示的页面快照”，不是历史页面。\n- 如果页面还在频繁重组或异步加载，建议等稳定后再抓一次。\n- 如果宿主调试导出逻辑有更新，需要重新安装宿主后才能看到新导出字段。\n\n\n# Issue Triage Report\n\n## Overall summary (counts by category, quick highlights)\n**总计议题数：** 45 个 (状态：open)\n\n**按类别统计：**\n* **Bug (缺陷):** 7 个 (含 3 个 P0)\n* **无障碍/权限:** 6 个 (含 2 个 P1)\n* **用户界面 (UI):** 11 个 (含 2 个 P1)\n* **工具/功能管理:** 9 个 (均为 P1/P2)\n* **工具/自动化:** 6 个 (含 2 个 P1)\n* **模型/API 集成:** 3 个 (含 1 个 P1)\n* **国际化 (i18n):** 1 个 (P1)\n* **配置/同步:** 1 个 (P1)\n* **模型 / AI 核心:** 2 个 (含 1 个 P1)\n* **数据导入/导出:** 1 个 (P2)\n* **应用分发:** 1 个 (P2)\n* **终端:** 1 个 (P1，与 UI 类别 #237 重叠)\n\n**快速亮点：**\n* **高优先级缺陷 (P0):** 存在 3 个关键 Bug，均导致核心的 UI 信息获取/自动化功能在特定系统上完全失效 (#125, #101, #67)。\n* **权限与兼容性问题突出：** 多个 P1 议题涉及 Android 系统（特别是 ColorOS、MIUI、鸿蒙）的权限授予失败、服务连接异常或文件访问问题 (#306, #283, #317)。\n* **功能建议集中：** 大量 P1/P2 议题围绕 **UI/UX 优化**、**自动化功能增强**、**AI 执行效率提升**（如安静模式、变量存储）和**配置管理**（如对话绑定模型、配置同步）提出建议。\n* **模型集成问题：** 存在通过 oneAPI 调用智谱模型失败 (#277) 和本地 llama.cpp 连接问题 (#258)，影响模型可用性。\n\n## Top priorities (P0 then P1)\n\n**P0 (关键缺陷，需立即调查):**\n1. **#125**: UI信息始终是Operit AI应用的 - AI 操作其他应用时获取自身 UI 信息，导致核心自动化功能失效。\n2. **#101**: [bug] UI调试工具无法获取当前屏幕内容 - 在 ColorOS 上触发系统返回，无法获取屏幕内容。\n3. **#67**: Miui 14.0.4 在debugger和root模式下均无法获取页面元素 - 在 MIUI 上 UI 数据获取完全失败。\n\n**P1 (高优先级功能/缺陷):**\n1. **#306**: [BUG]由于无障碍辅助app未申请任何权限，导致ColorOS无法解除权限限制 - 权限流程阻塞，影响核心功能启用。\n2. **#312**: English selected but large parts of UI still in Chinese - 国际化不完整，影响非中文用户体验。\n3. **#266**: 角色切换后主界面历史对话不显示，仅在悬浮窗显示 - 数据展示不一致，影响使用连贯性。\n4. **#283**: Bug: 无障碍服务已开启但AI助手接口服务显示未连接 - 服务状态指示错误，误导用户。\n5. **#317**: [bug]在Android8中，应用无法读取，修改Android设备本机中的文件 - 基础文件功能在特定系统失效。\n6. **#277**: 使用oneapi集成智谱code模型调用失败 - 第三方模型集成失败，影响功能可用性。\n7. **#321**: 添加配置同步功能 - 重要的用户体验增强功能，设计复杂度高。\n8. **#237**: 建议 (综合性UI/功能建议，含终端SSH想法)\n9. **#10**: 十条建议 (基础功能与UI改进建议集合)\n10. **#248**: 小功能拓展建议 (自动截图、连续对话、定时提醒等)\n11. **#35**: 请增加识图找图功能... (补充UI自动化能力)\n12. **#216**: Local llm implementation cpu/gpu/npu (支持本地LLM)\n13. **#165**: code_runner中的代码显示bug (显示格式错误)\n\n## By category (each category heading, list issues)\n\n### Bug (缺陷)\n* **#125 (P0)**: ui信息始终是Operit AI应用的 - AI操作其他应用时，获取的UI信息错误（始终是本应用），导致功能失效。 **行动：调查**\n* **#101 (P0)**: [bug] UI调试工具无法获取当前屏幕内容 - 在特定系统（Android 10 ColorOS）上，调用UI调试工具会触发系统返回，无法获取内容。 **行动：调查**\n* **#67 (P0)**: Miui 14.0.4 在debugger和root模式下均无法获取页面元素 - 在MIUI系统上，UI数据获取完全失败。 **行动：调查**\n* **#165 (P1)**: code_runner中的代码显示bug - code_runner显示代码时包含了前后标签，而非纯净代码。 **行动：修复**\n* **#27 (P2)**: 屏幕识别在某个软件里识别不出来东西 - 屏幕识别功能在特定软件中失效。 **行动：调查**\n* **#291 (P2)**: 导入聊天记录报错 - 导入聊天记录时失败，报错“未找到有效聊天记录”或“格式转换失败”。 **行动：调查**\n* **#263 (P2)**: 搜索引擎使用结果提取的问题 - 使用百度搜索后，提取搜索结果详情页内容时经常遇到 404 错误。 **行动：调查**\n\n### 无障碍/权限\n* **#306 (P1)**: [BUG]由于无障碍辅助app未申请任何权限，导致ColorOS无法解除权限限制 - 在 ColorOS 上，由于应用未申请常规权限，导致无法在设置中解除权限限制，进而无法授予无障碍权限。 **行动：修复**\n* **#283 (P1)**: Bug: 无障碍服务已开启但AI助手接口服务显示未连接 - 无障碍服务已开启，但应用内显示 AI 助手接口服务未连接。 **行动：调查**\n* **#317 (P1)**: [bug]在Android8中，应用无法读取，修改Android设备本机中的文件 - 在 Android 8 (鸿蒙2) 设备上，应用无法读写设备本地文件（尽管 `code_runner` 和 `shell` 可用）。 **行动：调查**\n* **#316 (P2)**: 关于APP被关联启动 - 应用在关闭状态下被关联启动并弹出无法滑掉的通知，影响用户体验，寻求关闭方法。 **行动：调查**\n* **#307 (P2)**: 语音助手功能可用性低 - 语音助手存在多个问题：手势启动后不能直接语音输入、识别失败率高、建议调用系统接口、界面图标辨识度低。 **行动：调查**\n* **#250 (部分内容) (P2)**: 自动化任务遇到双开软件提示或系统权限弹窗时无法识别并选择。 **行动：设计**\n\n### 用户界面 (UI)\n* **#266 (P1)**: 角色切换后主界面历史对话不显示，仅在悬浮窗显示 - 切换角色卡后，主界面无法加载对应历史对话，仅悬浮窗部分显示，数据不同步。 **行动：修复**\n* **#320 (P1)**: 1、你一个对话问问题... - 包含多个 UI 交互问题：多对话卡顿、waifu模式表格显示异常、窗口模式切换冲突、颜色选择器可视化不足。 **行动：调查**\n* **#237 (P1)**: 建议 - 包含多项UI改进建议，如对话框背景、权限管理等。**设计**\n* **#10 (P1)**: 十条建议 - 包含多项基础功能与UI改进建议，如输入交互、导航、主题等。**设计**\n* **#268 (P2)**: 全屏\n\n\n# GitHub Issues (AAswordman/Operit)\n\nState: `open`\nCount: `42`\n\n- #321 [添加配置同步功能](https://github.com/AAswordman/Operit/issues/321) (open)\n - comments: 1 | updated: 2026-01-11T07:26:48Z\n- #312 [English selected but large parts of UI still in Chinese (agents/artifacts/settings)](https://github.com/AAswordman/Operit/issues/312) (open)\n - comments: 3 | updated: 2026-01-10T11:28:06Z\n- #320 [1、你一个对话问问题，新打开一个对话再问一个，两个对话都会卡住。 2、waifu模式就不会发完整表格了，会把表格拆分成一行一行 3、小窗模式跟系统小窗跟最大模式有时候会冲突，在小窗模式显示回复，放大以后就不显示了，过一会突然卡出来。 4、各个地方的颜色选择变化时来点可视化就舒服了 5、调用shizuku时就巨慢，一点小小的任务要好久](https://github.com/AAswordman/Operit/issues/320) (open)\n - comments: 0 | updated: 2026-01-09T08:31:56Z\n- #319 [折叠对话](https://github.com/AAswordman/Operit/issues/319) (open)\n - comments: 0 | updated: 2026-01-07T18:13:40Z\n- #318 [一些功能性建议](https://github.com/AAswordman/Operit/issues/318) (open)\n - comments: 0 | updated: 2026-01-07T17:57:06Z\n- #317 [[bug]在Android8中，应用无法读取，修改Android设备本机中的文件](https://github.com/AAswordman/Operit/issues/317) (open)\n - comments: 0 | updated: 2026-01-06T14:21:18Z\n- #316 [关于APP被关联启动](https://github.com/AAswordman/Operit/issues/316) (open)\n - comments: 0 | updated: 2026-01-05T10:32:40Z\n- #311 [一些建议](https://github.com/AAswordman/Operit/issues/311) (open)\n - comments: 0 | updated: 2026-01-03T03:47:49Z\n- #277 [使用oneapi集成智谱code模型调用失败](https://github.com/AAswordman/Operit/issues/277) (open)\n - comments: 5 | updated: 2026-01-01T07:46:15Z\n- #307 [语音助手功能可用性低](https://github.com/AAswordman/Operit/issues/307) (open)\n - comments: 2 | updated: 2025-12-31T14:58:03Z\n- #306 [[BUG]由于无障碍辅助app未申请任何权限，导致ColorOS无法解除权限限制](https://github.com/AAswordman/Operit/issues/306) (open)\n - comments: 1 | updated: 2025-12-31T14:13:34Z\n- #300 [部分国行应用获取页面信息不正确](https://github.com/AAswordman/Operit/issues/300) (open)\n - comments: 2 | updated: 2025-12-31T01:56:23Z\n- #295 [记忆与记忆之间的链接只有创建和删除，没有修改](https://github.com/AAswordman/Operit/issues/295) (open)\n - comments: 1 | updated: 2025-12-21T02:08:50Z\n- #273 [建议上架到fdroid](https://github.com/AAswordman/Operit/issues/273) (open)\n - comments: 3 | updated: 2025-12-19T13:05:17Z\n- #291 [导入聊天记录报错](https://github.com/AAswordman/Operit/issues/291) (open)\n - comments: 0 | updated: 2025-12-18T08:22:29Z\n- #287 [【Request】对话绑定模型配置](https://github.com/AAswordman/Operit/issues/287) (open)\n - comments: 1 | updated: 2025-12-17T17:39:36Z\n- #283 [Bug: 无障碍服务已开启但AI助手接口服务显示未连接](https://github.com/AAswordman/Operit/issues/283) (open)\n - comments: 1 | updated: 2025-12-17T17:37:25Z\n- #267 [功能建议：操作屏幕录制、绘图功能、TIM适配等四大功能增强](https://github.com/AAswordman/Operit/issues/267) (open)\n - comments: 1 | updated: 2025-12-11T03:10:36Z\n- #265 [功能建议——安静模式](https://github.com/AAswordman/Operit/issues/265) (open)\n - comments: 1 | updated: 2025-12-11T02:17:10Z\n- #268 [全屏编辑提示词等内容时底部不会被输入法抬起](https://github.com/AAswordman/Operit/issues/268) (open)\n - comments: 0 | updated: 2025-12-10T01:08:33Z\n- #266 [角色切换后主界面历史对话不显示，仅在悬浮窗显示](https://github.com/AAswordman/Operit/issues/266) (open)\n - comments: 3 | updated: 2025-12-08T11:40:49Z\n- #264 [功能建议--变量](https://github.com/AAswordman/Operit/issues/264) (open)\n - comments: 1 | updated: 2025-12-07T11:38:13Z\n- #250 [一些建议和发现的问题](https://github.com/AAswordman/Operit/issues/250) (open)\n - comments: 6 | updated: 2025-12-07T09:21:04Z\n- #263 [搜索引擎使用结果提取的问题](https://github.com/AAswordman/Operit/issues/263) (open)\n - comments: 0 | updated: 2025-12-07T09:13:08Z\n- #258 [为什么请求不到llama.cpp啊](https://github.com/AAswordman/Operit/issues/258) (open)\n - comments: 1 | updated: 2025-11-22T07:56:22Z\n- #237 [建议](https://github.com/AAswordman/Operit/issues/237) (open)\n - labels: enhancement | comments: 3 | updated: 2025-11-12T06:07:20Z\n- #248 [小功能拓展建议](https://github.com/AAswordman/Operit/issues/248) (open)\n - comments: 0 | updated: 2025-11-08T05:35:45Z\n- #216 [Local llm implementation cpu/gpu/npu](https://github.com/AAswordman/Operit/issues/216) (open)\n - comments: 1 | updated: 2025-10-20T04:43:49Z\n- #214 [关于悬浮窗的建议](https://github.com/AAswordman/Operit/issues/214) (open)\n - comments: 0 | updated: 2025-10-15T00:55:58Z\n- #10 [十条建议](https://github.com/AAswordman/Operit/issues/10) (open)\n - labels: enhancement, good first issue | comments: 29 | updated: 2025-10-12T17:22:26Z\n- #165 [code_runner中的代码显示bug](https://github.com/AAswordman/Operit/issues/165) (open)\n - comments: 1 | updated: 2025-08-29T17:23:20Z\n- #138 [建议](https://github.com/AAswordman/Operit/issues/138) (open)\n - comments: 5 | updated: 2025-08-06T14:56:10Z\n- #125 [ui信息始终是Operit AI应用的](https://github.com/AAswordman/Operit/issues/125) (open)\n - comments: 8 | updated: 2025-08-03T17:03:38Z\n- #115 [小建议](https://github.com/AAswordman/Operit/issues/115) (open)\n - comments: 4 | updated: 2025-07-05T02:40:07Z\n- #35 [请增加识图找图功能，解决UI Automator识别不了画布上的自定义组件的缺陷。](https://github.com/AAswordman/Operit/issues/35) (open)\n - comments: 1 | updated: 2025-07-04T16:25:28Z\n- #108 [建议和bug](https://github.com/AAswordman/Operit/issues/108) (open)\n - comments: 8 | updated: 2025-07-02T04:58:07Z\n- #107 [几条建议](https://github.com/AAswordman/Operit/issues/107) (open)\n - labels: enhancement | comments: 1 | updated: 2025-06-30T18:05:48Z\n- #101 [[bug] UI调试工具无法获取当前屏幕内容](https://github.com/AAswordman/Operit/issues/101) (open)\n - comments: 1 | updated: 2025-06-28T10:09:36Z\n- #90 [能否在工具箱中添加一个查看触摸坐标的功能](https://github.com/AAswordman/Operit/issues/90) (open)\n - comments: 1 | updated: 2025-06-22T05:22:40Z\n- #78 [一些建议](https://github.com/AAswordman/Operit/issues/78) (open)\n - comments: 8 | updated: 2025-06-20T15:03:01Z\n- #67 [Miui 14.0.4 在debugger和root模式下均无法获取页面元素](https://github.com/AAswordman/Operit/issues/67) (open)\n - labels: bug | comments: 12 | updated: 2025-06-20T11:06:01Z\n- #27 [屏幕识别在某个软件里识别不出来东西](https://github.com/AAswordman/Operit/issues/27) (open)\n - comments: 1 | updated: 2025-06-07T05:38:57Z\n\n\n{\n \"name\": \"mcp-tcp-bridge\",\n \"version\": \"1.0.0\",\n \"description\": \"将STDIO型MCP服务器桥接到TCP端口\",\n \"main\": \"dist/index.js\",\n \"scripts\": {\n \"build\": \"tsc && pnpm run bundle && pnpm run copy\",\n \"bundle\": \"ncc build dist/index.js -o bundle && ncc build dist/spawn-helper.js -o bundle-helper\",\n \"copy\": \"node -e \\\"require('fs').copyFileSync('bundle/index.js', '../../app/src/main/assets/bridge/index.js')\\\" && node -e \\\"require('fs').copyFileSync('bundle-helper/index.js', '../../app/src/main/assets/bridge/spawn-helper.js')\\\"\",\n \"start\": \"node dist/index.js\",\n \"dev\": \"ts-node index.ts\",\n \"test\": \"echo \\\"Error: no test specified\\\" && exit 1\"\n },\n \"keywords\": [\n \"mcp\",\n \"bridge\",\n \"tcp\",\n \"stdio\"\n ],\n \"author\": \"\",\n \"license\": \"MIT\",\n \"dependencies\": {\n \"@modelcontextprotocol/sdk\": \"1.30.0\"\n },\n \"devDependencies\": {\n \"@types/node\": \"^18.0.0\",\n \"@vercel/ncc\": \"^0.38.1\",\n \"ts-node\": \"^10.9.1\",\n \"typescript\": \"^5.0.0\"\n }\n}\n\n\n{\n \"compilerOptions\": {\n \"target\": \"es2020\",\n \"module\": \"NodeNext\",\n \"outDir\": \"./dist\",\n \"rootDir\": \".\",\n \"strict\": true,\n \"esModuleInterop\": true,\n \"skipLibCheck\": true,\n \"forceConsistentCasingInFileNames\": true,\n \"resolveJsonModule\": true,\n \"moduleResolution\": \"NodeNext\",\n \"sourceMap\": true,\n \"declaration\": true,\n \"downlevelIteration\": true\n },\n \"include\": [\n \"*.ts\"\n ],\n \"exclude\": [\n \"node_modules\",\n \"dist\"\n ]\n}\n\n\n# compose_dsl artifact generator\n\nGenerates compose_dsl artifacts from Compose source jars in Gradle cache.\n\n- Kotlin renderer registry:\n - `app/src/main/java/com/ai/assistance/operit/ui/common/composedsl/ToolPkgComposeDslGeneratedRegistry.kt`\n- Kotlin renderers:\n - `app/src/main/java/com/ai/assistance/operit/ui/common/composedsl/ToolPkgComposeDslGeneratedRenderers.kt`\n- TypeScript generated bindings:\n - `examples/types/compose-dsl.material3.generated.d.ts`\n\nRun:\n\n```bash\npython tools/compose_dsl/generate_compose_dsl_artifacts.py\n```\n\nNotes:\n- Source jars are resolved from `~/.gradle/caches/modules-2/files-2.1`.\n- If jars are missing, sync/build once to download dependencies.\n- Generator behavior:\n - Keeps dedicated renderers for core complex nodes (TextField/Icon/Card/Surface, etc.).\n - Auto-discovers additional public `@Composable` functions from Material3/Foundation and\n generates generic renderers/registry/TS props when required params are mappable.\n - `ToolPkgComposeDslGeneratedRenderers.kt.tpl` is now a thin scaffold with helper functions;\n component renderers are injected at `// __GENERATED_COMPONENT_RENDERERS__`.\n\n\n# MCP TCP 桥接器\n\n这个工具只负责基于 STDIO 的本地 MCP 服务器与 TCP 客户端之间的桥接，让无法直接访问命名管道(FIFO)的客户端，例如 Android 应用，能够与本地进程通信。\n\n远程 HTTP Stream 和 SSE MCP 服务由 Android 端的 Kotlin MCP SDK 直接连接，不经过 bridge。\n\n## 功能特点\n\n- 将STDIO型MCP服务器桥接到TCP端口\n- 支持并发连接\n- 自动重启崩溃的MCP进程\n- 优雅地处理连接错误和进程终止\n- 详细的日志记录\n\n## 安装\n\n```bash\n# 在项目根目录安装工作区依赖\npnpm install\n\n# 编译 bridge 并同步 Android assets\npnpm --dir tools/mcp_bridge run build\n```\n\n`tools/mcp_bridge` 的依赖由根目录 `pnpm-lock.yaml` 统一锁定。构建会更新\n`app/src/main/assets/bridge/index.js` 和 `app/src/main/assets/bridge/spawn-helper.js`。\n\n## 使用方法\n\n### 基本用法\n\n```bash\n# 使用默认配置启动\npnpm --dir tools/mcp_bridge start\n```\n\n这将在默认端口8752上启动桥接器，连接到`../your-mcp-server.js`。\n\n### 高级用法\n\n您可以通过命令行参数自定义桥接器：\n\n```bash\n# 格式\npnpm --dir tools/mcp_bridge start -- [端口] [命令] [参数...]\n\n# 示例：在端口9000上启动，连接到Python MCP服务器\npnpm --dir tools/mcp_bridge start -- 9000 python ../python_mcp_server.py\n\n# 示例：连接到Java MCP服务器\npnpm --dir tools/mcp_bridge start -- 8752 java -jar ../java_mcp_server.jar\n```\n\n### 在代码中使用\n\n您也可以在其他Node.js应用中使用这个桥接器：\n\n```typescript\nimport McpBridge from './path/to/bridge';\n\nconst bridge = new McpBridge({\n port: 8752,\n host: '127.0.0.1',\n mcpCommand: 'node',\n mcpArgs: ['../your-mcp-server.js'],\n verbose: true\n});\n\nbridge.start();\n```\n\n## 在Termux中使用\n\n在Termux环境中，可以按以下步骤设置：\n\n```bash\n# 安装Node.js\npkg install nodejs\n\n# 克隆或下载此项目\ngit clone <项目URL>\ncd <项目目录>\n\n# 安装根工作区依赖\npnpm install\n\n# 编译并同步 Android assets\npnpm --dir tools/mcp_bridge run build\n\n# 启动桥接器\npnpm --dir tools/mcp_bridge start -- 8752 node ../your-mcp-server.js\n```\n\n## Android客户端示例\n\n以下是Android客户端连接到MCP桥接器的示例代码：\n\n```kotlin\nimport kotlinx.coroutines.Dispatchers\nimport kotlinx.coroutines.withContext\nimport java.io.BufferedReader\nimport java.io.InputStreamReader\nimport java.io.PrintWriter\nimport java.net.Socket\nimport org.json.JSONObject\n\nclass McpClient {\n private val host = \"127.0.0.1\"\n private val port = 8752\n \n suspend fun sendRequest(method: String, params: JSONObject): JSONObject = withContext(Dispatchers.IO) {\n Socket(host, port).use { socket ->\n val input = BufferedReader(InputStreamReader(socket.getInputStream()))\n val output = PrintWriter(socket.getOutputStream(), true)\n \n // 创建JSONRPC请求\n val requestId = System.currentTimeMillis().toString()\n val request = JSONObject().apply {\n put(\"jsonrpc\", \"2.0\")\n put(\"id\", requestId)\n put(\"method\", method)\n put(\"params\", params)\n }\n \n // 发送请求\n output.println(request.toString())\n \n // 读取响应\n val response = input.readLine()\n JSONObject(response)\n }\n }\n}\n```\n\n## 注意事项\n\n- 确保MCP服务器程序已正确安装并可执行\n- 桥接器应当与内部网络一起使用，不要暴露到公共互联网\n- 对于生产环境，考虑添加认证和加密层\n- 在Android环境中，确保应用有INTERNET权限\n"}