dsh-plugin-guide 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (374) hide show
  1. package/LICENSE +202 -0
  2. package/NOTICE.md +26 -0
  3. package/README.es.md +139 -0
  4. package/README.hi.md +138 -0
  5. package/README.md +165 -0
  6. package/README.pt.md +139 -0
  7. package/README.zh-CN.md +164 -0
  8. package/SKILL.md +69 -0
  9. package/cordis.patch.yml +4 -0
  10. package/guide/links.md +92 -0
  11. package/guide/plugin-dev-guide.md +429 -0
  12. package/guide/quick-reference.es.md +176 -0
  13. package/guide/quick-reference.hi.md +176 -0
  14. package/guide/quick-reference.md +176 -0
  15. package/guide/quick-reference.pt.md +176 -0
  16. package/guide/quick-reference.zh-CN.md +175 -0
  17. package/index.js +58 -0
  18. package/package.json +83 -0
  19. package/references/community-ecosystem.md +201 -0
  20. package/references/community-repo-deep-dive.md +695 -0
  21. package/references/cordis-paper-and-community.md +326 -0
  22. package/references/harness-repo.md +654 -0
  23. package/references/official-docs/AGENTS.md +149 -0
  24. package/references/official-docs/BENCHMARK.md +3 -0
  25. package/references/official-docs/CLAUDE.md +1 -0
  26. package/references/official-docs/CONTRIBUTING.i18n.yaml +6 -0
  27. package/references/official-docs/CONTRIBUTING.md +23 -0
  28. package/references/official-docs/CONTRIBUTING.zh.md +23 -0
  29. package/references/official-docs/LICENSE +21 -0
  30. package/references/official-docs/README.i18n.yaml +6 -0
  31. package/references/official-docs/README.md +35 -0
  32. package/references/official-docs/README.zh.md +74 -0
  33. package/references/official-docs/SNAPSHOT.md +16 -0
  34. package/references/official-docs/THIRD_PARTY_NOTICES.md +192 -0
  35. package/references/official-docs/docs/AGENTS.md +75 -0
  36. package/references/official-docs/docs/agent-lifecycle.i18n.yaml +6 -0
  37. package/references/official-docs/docs/agent-lifecycle.md +82 -0
  38. package/references/official-docs/docs/agent-lifecycle.zh.md +84 -0
  39. package/references/official-docs/docs/api-gateway.i18n.yaml +6 -0
  40. package/references/official-docs/docs/api-gateway.md +164 -0
  41. package/references/official-docs/docs/api-gateway.zh.md +164 -0
  42. package/references/official-docs/docs/architecture.i18n.yaml +6 -0
  43. package/references/official-docs/docs/architecture.md +129 -0
  44. package/references/official-docs/docs/architecture.zh.md +133 -0
  45. package/references/official-docs/docs/capability-seams.i18n.yaml +6 -0
  46. package/references/official-docs/docs/capability-seams.md +471 -0
  47. package/references/official-docs/docs/capability-seams.zh.md +473 -0
  48. package/references/official-docs/docs/config-catalog.i18n.yaml +6 -0
  49. package/references/official-docs/docs/config-catalog.md +3151 -0
  50. package/references/official-docs/docs/config-catalog.zh.md +3152 -0
  51. package/references/official-docs/docs/cookbook/adding-a-conversation-node.i18n.yaml +6 -0
  52. package/references/official-docs/docs/cookbook/adding-a-conversation-node.md +233 -0
  53. package/references/official-docs/docs/cookbook/adding-a-conversation-node.zh.md +233 -0
  54. package/references/official-docs/docs/cookbook/adding-a-package.i18n.yaml +6 -0
  55. package/references/official-docs/docs/cookbook/adding-a-package.md +118 -0
  56. package/references/official-docs/docs/cookbook/adding-a-package.zh.md +118 -0
  57. package/references/official-docs/docs/cookbook/adding-a-tool.i18n.yaml +6 -0
  58. package/references/official-docs/docs/cookbook/adding-a-tool.md +94 -0
  59. package/references/official-docs/docs/cookbook/adding-a-tool.zh.md +96 -0
  60. package/references/official-docs/docs/cookbook/adding-a-vendored-package.i18n.yaml +6 -0
  61. package/references/official-docs/docs/cookbook/adding-a-vendored-package.md +59 -0
  62. package/references/official-docs/docs/cookbook/adding-a-vendored-package.zh.md +59 -0
  63. package/references/official-docs/docs/cookbook/adding-an-llm-adapter.i18n.yaml +6 -0
  64. package/references/official-docs/docs/cookbook/adding-an-llm-adapter.md +43 -0
  65. package/references/official-docs/docs/cookbook/adding-an-llm-adapter.zh.md +43 -0
  66. package/references/official-docs/docs/cookbook/extension-cookbook.i18n.yaml +6 -0
  67. package/references/official-docs/docs/cookbook/extension-cookbook.md +129 -0
  68. package/references/official-docs/docs/cookbook/extension-cookbook.zh.md +131 -0
  69. package/references/official-docs/docs/cookbook/maintaining-dsh-code-review.i18n.yaml +6 -0
  70. package/references/official-docs/docs/cookbook/maintaining-dsh-code-review.md +64 -0
  71. package/references/official-docs/docs/cookbook/maintaining-dsh-code-review.zh.md +64 -0
  72. package/references/official-docs/docs/cookbook/responding-to-pr-review-on-a-stack.i18n.yaml +6 -0
  73. package/references/official-docs/docs/cookbook/responding-to-pr-review-on-a-stack.md +32 -0
  74. package/references/official-docs/docs/cookbook/responding-to-pr-review-on-a-stack.zh.md +32 -0
  75. package/references/official-docs/docs/cordis-api/context.i18n.yaml +6 -0
  76. package/references/official-docs/docs/cordis-api/context.md +364 -0
  77. package/references/official-docs/docs/cordis-api/context.zh.md +366 -0
  78. package/references/official-docs/docs/cordis-api/events.i18n.yaml +6 -0
  79. package/references/official-docs/docs/cordis-api/events.md +207 -0
  80. package/references/official-docs/docs/cordis-api/events.zh.md +209 -0
  81. package/references/official-docs/docs/cordis-api/fiber.i18n.yaml +6 -0
  82. package/references/official-docs/docs/cordis-api/fiber.md +375 -0
  83. package/references/official-docs/docs/cordis-api/fiber.zh.md +377 -0
  84. package/references/official-docs/docs/cordis-api/inherited.md +39 -0
  85. package/references/official-docs/docs/cordis-api/registry.i18n.yaml +6 -0
  86. package/references/official-docs/docs/cordis-api/registry.md +152 -0
  87. package/references/official-docs/docs/cordis-api/registry.zh.md +154 -0
  88. package/references/official-docs/docs/cordis-api/service.i18n.yaml +6 -0
  89. package/references/official-docs/docs/cordis-api/service.md +102 -0
  90. package/references/official-docs/docs/cordis-api/service.zh.md +104 -0
  91. package/references/official-docs/docs/cordis-primer.i18n.yaml +6 -0
  92. package/references/official-docs/docs/cordis-primer.md +44 -0
  93. package/references/official-docs/docs/cordis-primer.zh.md +50 -0
  94. package/references/official-docs/docs/cordis-tutorial/01-first-plugin.i18n.yaml +6 -0
  95. package/references/official-docs/docs/cordis-tutorial/01-first-plugin.md +95 -0
  96. package/references/official-docs/docs/cordis-tutorial/01-first-plugin.zh.md +95 -0
  97. package/references/official-docs/docs/cordis-tutorial/02-lifecycle-and-effects.i18n.yaml +6 -0
  98. package/references/official-docs/docs/cordis-tutorial/02-lifecycle-and-effects.md +98 -0
  99. package/references/official-docs/docs/cordis-tutorial/02-lifecycle-and-effects.zh.md +98 -0
  100. package/references/official-docs/docs/cordis-tutorial/03-services.i18n.yaml +6 -0
  101. package/references/official-docs/docs/cordis-tutorial/03-services.md +98 -0
  102. package/references/official-docs/docs/cordis-tutorial/03-services.zh.md +98 -0
  103. package/references/official-docs/docs/cordis-tutorial/04-events.i18n.yaml +6 -0
  104. package/references/official-docs/docs/cordis-tutorial/04-events.md +144 -0
  105. package/references/official-docs/docs/cordis-tutorial/04-events.zh.md +144 -0
  106. package/references/official-docs/docs/cordis-tutorial/05-config.i18n.yaml +6 -0
  107. package/references/official-docs/docs/cordis-tutorial/05-config.md +84 -0
  108. package/references/official-docs/docs/cordis-tutorial/05-config.zh.md +84 -0
  109. package/references/official-docs/docs/cordis-tutorial/06-composition-and-hmr.i18n.yaml +6 -0
  110. package/references/official-docs/docs/cordis-tutorial/06-composition-and-hmr.md +113 -0
  111. package/references/official-docs/docs/cordis-tutorial/06-composition-and-hmr.zh.md +113 -0
  112. package/references/official-docs/docs/cordis-tutorial/07-into-the-harness.i18n.yaml +6 -0
  113. package/references/official-docs/docs/cordis-tutorial/07-into-the-harness.md +107 -0
  114. package/references/official-docs/docs/cordis-tutorial/07-into-the-harness.zh.md +107 -0
  115. package/references/official-docs/docs/cordis-tutorial/index.i18n.yaml +6 -0
  116. package/references/official-docs/docs/cordis-tutorial/index.md +60 -0
  117. package/references/official-docs/docs/cordis-tutorial/index.zh.md +62 -0
  118. package/references/official-docs/docs/defensive-patterns.i18n.yaml +6 -0
  119. package/references/official-docs/docs/defensive-patterns.md +33 -0
  120. package/references/official-docs/docs/defensive-patterns.zh.md +33 -0
  121. package/references/official-docs/docs/development.i18n.yaml +6 -0
  122. package/references/official-docs/docs/development.md +171 -0
  123. package/references/official-docs/docs/development.zh.md +171 -0
  124. package/references/official-docs/docs/event-producer-consumer.i18n.yaml +6 -0
  125. package/references/official-docs/docs/event-producer-consumer.md +76 -0
  126. package/references/official-docs/docs/event-producer-consumer.zh.md +78 -0
  127. package/references/official-docs/docs/glossary.i18n.yaml +6 -0
  128. package/references/official-docs/docs/glossary.md +45 -0
  129. package/references/official-docs/docs/glossary.zh.md +45 -0
  130. package/references/official-docs/docs/graph-atlas.i18n.yaml +6 -0
  131. package/references/official-docs/docs/graph-atlas.md +24 -0
  132. package/references/official-docs/docs/graph-atlas.zh.md +26 -0
  133. package/references/official-docs/docs/i18n/README.i18n.yaml +6 -0
  134. package/references/official-docs/docs/i18n/README.md +60 -0
  135. package/references/official-docs/docs/i18n/README.zh.md +60 -0
  136. package/references/official-docs/docs/i18n/style-samples.md +87 -0
  137. package/references/official-docs/docs/i18n/terminology.md +214 -0
  138. package/references/official-docs/docs/i18n/translation-prompt.md +263 -0
  139. package/references/official-docs/docs/i18n/translation-rules.i18n.yaml +6 -0
  140. package/references/official-docs/docs/i18n/translation-rules.md +69 -0
  141. package/references/official-docs/docs/i18n/translation-rules.zh.md +69 -0
  142. package/references/official-docs/docs/module-graph.i18n.yaml +6 -0
  143. package/references/official-docs/docs/module-graph.md +1638 -0
  144. package/references/official-docs/docs/module-graph.zh.md +1640 -0
  145. package/references/official-docs/docs/persistence-catalog.i18n.yaml +6 -0
  146. package/references/official-docs/docs/persistence-catalog.md +944 -0
  147. package/references/official-docs/docs/persistence-catalog.zh.md +946 -0
  148. package/references/official-docs/docs/postmortem/0001-acp-default-export-drops-inject.i18n.yaml +6 -0
  149. package/references/official-docs/docs/postmortem/0001-acp-default-export-drops-inject.md +113 -0
  150. package/references/official-docs/docs/postmortem/0001-acp-default-export-drops-inject.zh.md +113 -0
  151. package/references/official-docs/docs/postmortem/0002-js-expression-disabled-filesystem-tools.i18n.yaml +6 -0
  152. package/references/official-docs/docs/postmortem/0002-js-expression-disabled-filesystem-tools.md +47 -0
  153. package/references/official-docs/docs/postmortem/0002-js-expression-disabled-filesystem-tools.zh.md +47 -0
  154. package/references/official-docs/docs/postmortem/0003-web-agent-gui-feedback-loop.i18n.yaml +6 -0
  155. package/references/official-docs/docs/postmortem/0003-web-agent-gui-feedback-loop.md +53 -0
  156. package/references/official-docs/docs/postmortem/0003-web-agent-gui-feedback-loop.zh.md +53 -0
  157. package/references/official-docs/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.i18n.yaml +6 -0
  158. package/references/official-docs/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.md +55 -0
  159. package/references/official-docs/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.zh.md +55 -0
  160. package/references/official-docs/docs/postmortem/README.i18n.yaml +6 -0
  161. package/references/official-docs/docs/postmortem/README.md +18 -0
  162. package/references/official-docs/docs/postmortem/README.zh.md +18 -0
  163. package/references/official-docs/docs/rescope.i18n.yaml +6 -0
  164. package/references/official-docs/docs/rescope.md +53 -0
  165. package/references/official-docs/docs/rescope.zh.md +53 -0
  166. package/references/official-docs/docs/subsystems/README.i18n.yaml +6 -0
  167. package/references/official-docs/docs/subsystems/README.md +55 -0
  168. package/references/official-docs/docs/subsystems/README.zh.md +55 -0
  169. package/references/official-docs/docs/subsystems/approval.i18n.yaml +6 -0
  170. package/references/official-docs/docs/subsystems/approval.md +170 -0
  171. package/references/official-docs/docs/subsystems/approval.zh.md +170 -0
  172. package/references/official-docs/docs/subsystems/attachment.i18n.yaml +6 -0
  173. package/references/official-docs/docs/subsystems/attachment.md +115 -0
  174. package/references/official-docs/docs/subsystems/attachment.zh.md +115 -0
  175. package/references/official-docs/docs/subsystems/client-modules.i18n.yaml +6 -0
  176. package/references/official-docs/docs/subsystems/client-modules.md +118 -0
  177. package/references/official-docs/docs/subsystems/client-modules.zh.md +118 -0
  178. package/references/official-docs/docs/subsystems/code-runtime.i18n.yaml +6 -0
  179. package/references/official-docs/docs/subsystems/code-runtime.md +191 -0
  180. package/references/official-docs/docs/subsystems/code-runtime.zh.md +191 -0
  181. package/references/official-docs/docs/subsystems/commands.i18n.yaml +6 -0
  182. package/references/official-docs/docs/subsystems/commands.md +187 -0
  183. package/references/official-docs/docs/subsystems/commands.zh.md +187 -0
  184. package/references/official-docs/docs/subsystems/compaction.i18n.yaml +6 -0
  185. package/references/official-docs/docs/subsystems/compaction.md +238 -0
  186. package/references/official-docs/docs/subsystems/compaction.zh.md +238 -0
  187. package/references/official-docs/docs/subsystems/core.i18n.yaml +6 -0
  188. package/references/official-docs/docs/subsystems/core.md +1070 -0
  189. package/references/official-docs/docs/subsystems/core.zh.md +1078 -0
  190. package/references/official-docs/docs/subsystems/credentials.i18n.yaml +6 -0
  191. package/references/official-docs/docs/subsystems/credentials.md +133 -0
  192. package/references/official-docs/docs/subsystems/credentials.zh.md +133 -0
  193. package/references/official-docs/docs/subsystems/extensions.i18n.yaml +6 -0
  194. package/references/official-docs/docs/subsystems/extensions.md +364 -0
  195. package/references/official-docs/docs/subsystems/extensions.zh.md +364 -0
  196. package/references/official-docs/docs/subsystems/feedback.i18n.yaml +6 -0
  197. package/references/official-docs/docs/subsystems/feedback.md +266 -0
  198. package/references/official-docs/docs/subsystems/feedback.zh.md +266 -0
  199. package/references/official-docs/docs/subsystems/filesystem.i18n.yaml +6 -0
  200. package/references/official-docs/docs/subsystems/filesystem.md +495 -0
  201. package/references/official-docs/docs/subsystems/filesystem.zh.md +495 -0
  202. package/references/official-docs/docs/subsystems/goal.i18n.yaml +6 -0
  203. package/references/official-docs/docs/subsystems/goal.md +277 -0
  204. package/references/official-docs/docs/subsystems/goal.zh.md +277 -0
  205. package/references/official-docs/docs/subsystems/invariants.i18n.yaml +6 -0
  206. package/references/official-docs/docs/subsystems/invariants.md +88 -0
  207. package/references/official-docs/docs/subsystems/invariants.zh.md +88 -0
  208. package/references/official-docs/docs/subsystems/jobs.i18n.yaml +6 -0
  209. package/references/official-docs/docs/subsystems/jobs.md +290 -0
  210. package/references/official-docs/docs/subsystems/jobs.zh.md +290 -0
  211. package/references/official-docs/docs/subsystems/llm-streaming.i18n.yaml +6 -0
  212. package/references/official-docs/docs/subsystems/llm-streaming.md +888 -0
  213. package/references/official-docs/docs/subsystems/llm-streaming.zh.md +894 -0
  214. package/references/official-docs/docs/subsystems/lsp.i18n.yaml +6 -0
  215. package/references/official-docs/docs/subsystems/lsp.md +202 -0
  216. package/references/official-docs/docs/subsystems/lsp.zh.md +202 -0
  217. package/references/official-docs/docs/subsystems/permission-presets.i18n.yaml +6 -0
  218. package/references/official-docs/docs/subsystems/permission-presets.md +131 -0
  219. package/references/official-docs/docs/subsystems/permission-presets.zh.md +131 -0
  220. package/references/official-docs/docs/subsystems/persistence.i18n.yaml +6 -0
  221. package/references/official-docs/docs/subsystems/persistence.md +385 -0
  222. package/references/official-docs/docs/subsystems/persistence.zh.md +385 -0
  223. package/references/official-docs/docs/subsystems/plan.i18n.yaml +6 -0
  224. package/references/official-docs/docs/subsystems/plan.md +87 -0
  225. package/references/official-docs/docs/subsystems/plan.zh.md +87 -0
  226. package/references/official-docs/docs/subsystems/sandbox.i18n.yaml +6 -0
  227. package/references/official-docs/docs/subsystems/sandbox.md +218 -0
  228. package/references/official-docs/docs/subsystems/sandbox.zh.md +218 -0
  229. package/references/official-docs/docs/subsystems/schedule.i18n.yaml +6 -0
  230. package/references/official-docs/docs/subsystems/schedule.md +186 -0
  231. package/references/official-docs/docs/subsystems/schedule.zh.md +186 -0
  232. package/references/official-docs/docs/subsystems/scope.i18n.yaml +6 -0
  233. package/references/official-docs/docs/subsystems/scope.md +59 -0
  234. package/references/official-docs/docs/subsystems/scope.zh.md +59 -0
  235. package/references/official-docs/docs/subsystems/session-projection.i18n.yaml +6 -0
  236. package/references/official-docs/docs/subsystems/session-projection.md +262 -0
  237. package/references/official-docs/docs/subsystems/session-projection.zh.md +262 -0
  238. package/references/official-docs/docs/subsystems/session-query.i18n.yaml +6 -0
  239. package/references/official-docs/docs/subsystems/session-query.md +495 -0
  240. package/references/official-docs/docs/subsystems/session-query.zh.md +495 -0
  241. package/references/official-docs/docs/subsystems/session-reference.i18n.yaml +6 -0
  242. package/references/official-docs/docs/subsystems/session-reference.md +108 -0
  243. package/references/official-docs/docs/subsystems/session-reference.zh.md +108 -0
  244. package/references/official-docs/docs/subsystems/session-telemetry.i18n.yaml +6 -0
  245. package/references/official-docs/docs/subsystems/session-telemetry.md +194 -0
  246. package/references/official-docs/docs/subsystems/session-telemetry.zh.md +194 -0
  247. package/references/official-docs/docs/subsystems/session-title.i18n.yaml +6 -0
  248. package/references/official-docs/docs/subsystems/session-title.md +204 -0
  249. package/references/official-docs/docs/subsystems/session-title.zh.md +204 -0
  250. package/references/official-docs/docs/subsystems/session.i18n.yaml +6 -0
  251. package/references/official-docs/docs/subsystems/session.md +849 -0
  252. package/references/official-docs/docs/subsystems/session.zh.md +851 -0
  253. package/references/official-docs/docs/subsystems/settings.i18n.yaml +6 -0
  254. package/references/official-docs/docs/subsystems/settings.md +310 -0
  255. package/references/official-docs/docs/subsystems/settings.zh.md +310 -0
  256. package/references/official-docs/docs/subsystems/shell.i18n.yaml +6 -0
  257. package/references/official-docs/docs/subsystems/shell.md +303 -0
  258. package/references/official-docs/docs/subsystems/shell.zh.md +303 -0
  259. package/references/official-docs/docs/subsystems/skills.i18n.yaml +6 -0
  260. package/references/official-docs/docs/subsystems/skills.md +331 -0
  261. package/references/official-docs/docs/subsystems/skills.zh.md +331 -0
  262. package/references/official-docs/docs/subsystems/spill.i18n.yaml +6 -0
  263. package/references/official-docs/docs/subsystems/spill.md +117 -0
  264. package/references/official-docs/docs/subsystems/spill.zh.md +117 -0
  265. package/references/official-docs/docs/subsystems/storage.i18n.yaml +6 -0
  266. package/references/official-docs/docs/subsystems/storage.md +229 -0
  267. package/references/official-docs/docs/subsystems/storage.zh.md +229 -0
  268. package/references/official-docs/docs/subsystems/subagent.i18n.yaml +6 -0
  269. package/references/official-docs/docs/subsystems/subagent.md +734 -0
  270. package/references/official-docs/docs/subsystems/subagent.zh.md +736 -0
  271. package/references/official-docs/docs/subsystems/subprocess.i18n.yaml +6 -0
  272. package/references/official-docs/docs/subsystems/subprocess.md +324 -0
  273. package/references/official-docs/docs/subsystems/subprocess.zh.md +324 -0
  274. package/references/official-docs/docs/subsystems/system-prompt.i18n.yaml +6 -0
  275. package/references/official-docs/docs/subsystems/system-prompt.md +207 -0
  276. package/references/official-docs/docs/subsystems/system-prompt.zh.md +207 -0
  277. package/references/official-docs/docs/subsystems/terminal.i18n.yaml +6 -0
  278. package/references/official-docs/docs/subsystems/terminal.md +184 -0
  279. package/references/official-docs/docs/subsystems/terminal.zh.md +184 -0
  280. package/references/official-docs/docs/subsystems/token-meter.i18n.yaml +6 -0
  281. package/references/official-docs/docs/subsystems/token-meter.md +90 -0
  282. package/references/official-docs/docs/subsystems/token-meter.zh.md +90 -0
  283. package/references/official-docs/docs/subsystems/tools.i18n.yaml +6 -0
  284. package/references/official-docs/docs/subsystems/tools.md +720 -0
  285. package/references/official-docs/docs/subsystems/tools.zh.md +720 -0
  286. package/references/official-docs/docs/subsystems/typert.i18n.yaml +6 -0
  287. package/references/official-docs/docs/subsystems/typert.md +336 -0
  288. package/references/official-docs/docs/subsystems/typert.zh.md +336 -0
  289. package/references/official-docs/docs/subsystems/user-questions.i18n.yaml +6 -0
  290. package/references/official-docs/docs/subsystems/user-questions.md +178 -0
  291. package/references/official-docs/docs/subsystems/user-questions.zh.md +178 -0
  292. package/references/official-docs/docs/subsystems/web-server.i18n.yaml +6 -0
  293. package/references/official-docs/docs/subsystems/web-server.md +108 -0
  294. package/references/official-docs/docs/subsystems/web-server.zh.md +108 -0
  295. package/references/official-docs/docs/subsystems/web.i18n.yaml +6 -0
  296. package/references/official-docs/docs/subsystems/web.md +199 -0
  297. package/references/official-docs/docs/subsystems/web.zh.md +199 -0
  298. package/references/official-docs/docs/subsystems/workflow.i18n.yaml +6 -0
  299. package/references/official-docs/docs/subsystems/workflow.md +278 -0
  300. package/references/official-docs/docs/subsystems/workflow.zh.md +278 -0
  301. package/references/official-docs/docs/subsystems/workspace.i18n.yaml +6 -0
  302. package/references/official-docs/docs/subsystems/workspace.md +228 -0
  303. package/references/official-docs/docs/subsystems/workspace.zh.md +228 -0
  304. package/references/official-docs/docs/testing.i18n.yaml +6 -0
  305. package/references/official-docs/docs/testing.md +49 -0
  306. package/references/official-docs/docs/testing.zh.md +49 -0
  307. package/references/official-docs/docs/tool-catalog.i18n.yaml +6 -0
  308. package/references/official-docs/docs/tool-catalog.md +1873 -0
  309. package/references/official-docs/docs/tool-catalog.zh.md +1878 -0
  310. package/references/official-docs/docs/tool-execution-pipeline.i18n.yaml +6 -0
  311. package/references/official-docs/docs/tool-execution-pipeline.md +62 -0
  312. package/references/official-docs/docs/tool-execution-pipeline.zh.md +64 -0
  313. package/references/official-docs/docs/user/develop/basic/config.i18n.yaml +6 -0
  314. package/references/official-docs/docs/user/develop/basic/config.md +106 -0
  315. package/references/official-docs/docs/user/develop/basic/config.zh.md +106 -0
  316. package/references/official-docs/docs/user/develop/basic/index.i18n.yaml +6 -0
  317. package/references/official-docs/docs/user/develop/basic/index.md +144 -0
  318. package/references/official-docs/docs/user/develop/basic/index.zh.md +144 -0
  319. package/references/official-docs/docs/user/develop/basic/publish.i18n.yaml +6 -0
  320. package/references/official-docs/docs/user/develop/basic/publish.md +183 -0
  321. package/references/official-docs/docs/user/develop/basic/publish.zh.md +183 -0
  322. package/references/official-docs/docs/user/develop/basic/tool.i18n.yaml +6 -0
  323. package/references/official-docs/docs/user/develop/basic/tool.md +52 -0
  324. package/references/official-docs/docs/user/develop/basic/tool.zh.md +52 -0
  325. package/references/official-docs/docs/user/develop/framework/events.i18n.yaml +6 -0
  326. package/references/official-docs/docs/user/develop/framework/events.md +143 -0
  327. package/references/official-docs/docs/user/develop/framework/events.zh.md +143 -0
  328. package/references/official-docs/docs/user/develop/framework/index.i18n.yaml +6 -0
  329. package/references/official-docs/docs/user/develop/framework/index.md +137 -0
  330. package/references/official-docs/docs/user/develop/framework/index.zh.md +137 -0
  331. package/references/official-docs/docs/user/develop/framework/service.i18n.yaml +6 -0
  332. package/references/official-docs/docs/user/develop/framework/service.md +148 -0
  333. package/references/official-docs/docs/user/develop/framework/service.zh.md +150 -0
  334. package/references/official-docs/docs/user/develop/practice/index.i18n.yaml +6 -0
  335. package/references/official-docs/docs/user/develop/practice/index.md +155 -0
  336. package/references/official-docs/docs/user/develop/practice/index.zh.md +155 -0
  337. package/references/official-docs/docs/user/develop/practice/llm-adapter.i18n.yaml +6 -0
  338. package/references/official-docs/docs/user/develop/practice/llm-adapter.md +188 -0
  339. package/references/official-docs/docs/user/develop/practice/llm-adapter.zh.md +188 -0
  340. package/references/official-docs/docs/user/guide/index.i18n.yaml +6 -0
  341. package/references/official-docs/docs/user/guide/index.md +30 -0
  342. package/references/official-docs/docs/user/guide/index.zh.md +30 -0
  343. package/references/official-docs/docs/user/guide/providers-custom-form.png +0 -0
  344. package/references/official-docs/docs/user/guide/providers-custom-form.zh.png +0 -0
  345. package/references/official-docs/docs/user/guide/providers-models-page.png +0 -0
  346. package/references/official-docs/docs/user/guide/providers-models-page.zh.png +0 -0
  347. package/references/official-docs/docs/user/guide/providers.i18n.yaml +6 -0
  348. package/references/official-docs/docs/user/guide/providers.md +98 -0
  349. package/references/official-docs/docs/user/guide/providers.zh.md +98 -0
  350. package/references/official-docs/docs/user/guide/python-sdk.i18n.yaml +6 -0
  351. package/references/official-docs/docs/user/guide/python-sdk.md +104 -0
  352. package/references/official-docs/docs/user/guide/python-sdk.zh.md +104 -0
  353. package/references/official-docs/docs/user/index.i18n.yaml +6 -0
  354. package/references/official-docs/docs/user/index.md +11 -0
  355. package/references/official-docs/docs/user/index.zh.md +11 -0
  356. package/references/official-docs/docs/web-styling.i18n.yaml +6 -0
  357. package/references/official-docs/docs/web-styling.md +25 -0
  358. package/references/official-docs/docs/web-styling.zh.md +25 -0
  359. package/references/official-docs/examples/AGENTS.md +20 -0
  360. package/references/official-docs/packages/AGENTS.md +27 -0
  361. package/references/official-docs/packages/README.md +69 -0
  362. package/references/official-docs/vendor/README.md +60 -0
  363. package/references/official-docs/website-docs.ts +524 -0
  364. package/references/sources.md +137 -0
  365. package/references/upstream-cordis.md +594 -0
  366. package/references/website-pages.md +668 -0
  367. package/scripts/archive-discussions.ps1 +154 -0
  368. package/scripts/download-community-articles.ps1 +188 -0
  369. package/scripts/download-community-repos.ps1 +232 -0
  370. package/scripts/download-sources.ps1 +195 -0
  371. package/scripts/gen-topic-snapshot.ps1 +91 -0
  372. package/scripts/install-skill.ps1 +63 -0
  373. package/scripts/sync-official-docs.ps1 +130 -0
  374. package/scripts/verify-kit.ps1 +191 -0
@@ -0,0 +1,199 @@
1
+ # Web Access
2
+
3
+ English | [中文](web.zh.md)
4
+
5
+ The web access seam — a [capability seam](../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md) that spans **two operations** (search and fetch) on one `ctx.web` service, split across packages: Service Definition ([dsh-web](../../packages/web/web), `ctx.web` + the provider registries), Service Providers ([dsh-web-search-exa](../../packages/web/web-search-exa), [dsh-web-search-perplexity](../../packages/web/web-search-perplexity), [dsh-web-search-deepseek](../../packages/web/web-search-deepseek), [dsh-web-fetch-http](../../packages/web/web-fetch-http)), and Consumer ([dsh-tool-web](../../packages/web/tool-web), the `web_search`/`web_fetch` tool schemas). Web is **one optional capability**, not part of the agent-loop spine — so its vocabulary lives here, not in [core.md](core.md). A search-provider swap does not change how the model asks for a query, and a fetch-provider swap does not change how the model asks for a URL.
6
+
7
+ Source: [`packages/web/web/src/types.ts`](../../packages/web/web/src/types.ts)
8
+
9
+ ## Why one capability has two operations
10
+
11
+ Search and fetch share no request schema and no business logic, but they are deliberately one `ctx.web` middle layer: one provider-selection policy owner, one abort/error vocabulary, and one product-facing "how this harness reaches the web" configuration API. The cost is the parallel `searchX`/`fetchX` method pairs on the service; that parallelism is intentional, not a missed extraction. Providers register **capabilities** (a `WebSearchProvider` or `WebFetchProvider`), not tools; the model-facing names, schemas, prompt guidance, and presentation all live in the single `dsh-tool-web` consumer.
12
+
13
+ ## Search request and result
14
+
15
+ The model-facing tool argument is just a `query`; `maxResults` is a consumer-owned bound (`dsh-tool-web`'s `searchMaxResults` config, default `8`) passed through the seam and enforced on the way back — if a provider over-returns, the seam truncates `sources[]` and sets `truncated`.
16
+
17
+ ```ts type-equiv
18
+ /**
19
+ * What one search-capable backend can return. The model-facing argument is just
20
+ * a query; `maxResults` is a `dsh-tool-web`-layer bound passed through unchanged
21
+ * and enforced on the way back by the seam (see {@link WebSearchResult}).
22
+ */
23
+ interface WebSearchRequest {
24
+ readonly query: string
25
+ /**
26
+ * Upper bound on returned sources; the seam truncates to it. Omitted = no
27
+ * bound. `dsh-tool-web` always sets it. A provider whose API supports a
28
+ * result-count control (Exa's `numResults`) should apply it at the request
29
+ * layer as a cost/latency optimization; the seam enforces the bound
30
+ * regardless.
31
+ */
32
+ readonly maxResults?: number
33
+ }
34
+ ```
35
+
36
+ ```ts type-equiv
37
+ /**
38
+ * Normalized search outcome. `content` is optional provider-generated answer
39
+ * text or summary (Exa and DeepSeek return none; Perplexity returns a
40
+ * generated answer).
41
+ * `sources[]` is the portable citation shape. `truncated` is set by the seam
42
+ * when it cut `sources[]` down to `maxResults`.
43
+ */
44
+ interface WebSearchResult {
45
+ /** Optional provider-generated answer text, search context, or summary. */
46
+ readonly content?: string
47
+ /** Citeable sources, already truncated to the request's `maxResults`. */
48
+ readonly sources: readonly WebSearchSource[]
49
+ /** True when the seam dropped sources to honor `maxResults`. */
50
+ readonly truncated: boolean
51
+ }
52
+ ```
53
+
54
+ ```ts type-equiv
55
+ /**
56
+ * One citeable source. A source always has a URL; `title`, `snippet`, and
57
+ * `publishedAt` are optional because not every provider returns them — forcing
58
+ * adapters to invent them would make the seam lie (Perplexity citations may be
59
+ * URL-only). `dsh-tool-web` renders `title ?? hostname(url)` for display.
60
+ */
61
+ interface WebSearchSource {
62
+ readonly url: string
63
+ readonly title?: string
64
+ readonly snippet?: string
65
+ /** Publication/crawl timestamp as a provider-supplied ISO-8601 string. */
66
+ readonly publishedAt?: string
67
+ }
68
+ ```
69
+
70
+ ## Fetch request and result
71
+
72
+ ```ts type-equiv
73
+ /**
74
+ * What one fetch-capable backend is asked to retrieve. The request deliberately
75
+ * omits timeout, format, prompt, and extraction controls: cancellation is a
76
+ * direct execution argument, while presentation and higher-level LLM concerns
77
+ * belong outside safe retrieval.
78
+ */
79
+ interface WebFetchRequest {
80
+ readonly url: string
81
+ }
82
+ ```
83
+
84
+ HTTP status is part of the fetched resource state, not automatically a failure: a successful network fetch of a `404`/`500` returns a `WebFetchResult` with the status code and a bounded decoded body. `url` is the final URL after allowed redirects. `WebError` is reserved for failures to safely retrieve or represent the resource.
85
+
86
+ ```ts type-equiv
87
+ /**
88
+ * Normalized fetch outcome. A successful network fetch of a non-2xx response is
89
+ * a result, not an error: the status code is part of the fetched resource
90
+ * state. {@link WebError} is reserved for failures to safely retrieve or
91
+ * represent the resource.
92
+ */
93
+ interface WebFetchResult {
94
+ /** The final URL after allowed redirects (the request URL is in the request). */
95
+ readonly url: string
96
+ /** HTTP status code of the fetched response. */
97
+ readonly statusCode: number
98
+ /** Decoded body, classified by content kind. */
99
+ readonly body: WebFetchBody
100
+ /** True when the provider capped the decoded body. */
101
+ readonly truncated: boolean
102
+ }
103
+ ```
104
+
105
+ ```ts type-equiv
106
+ /**
107
+ * The decoded body of a fetched resource. A CLOSED discriminated union owned by
108
+ * `dsh-web`: the provider decodes the kind and `dsh-tool-web` renders it, so a
109
+ * new kind is a coordinated change across known packages, not a plugin
110
+ * extension. Consumers `switch` on `kind` ending in `default: assertNever(...)`
111
+ * so adding a kind breaks compilation at every consumer until handled. Each arm
112
+ * stays its own object literal even where fields coincide, so an arm can gain
113
+ * fields the others lack.
114
+ */
115
+ type WebFetchBody =
116
+ | { readonly kind: 'html'; readonly content: string }
117
+ | { readonly kind: 'text'; readonly content: string }
118
+ ```
119
+
120
+ ## Provider availability
121
+
122
+ A provider's `available(): boolean` is a cheap LOCAL check (credential presence, parseable config) and **must not make network calls**. It is an input to execution-time selection, not a health system: `search()`/`fetch()` read it to pick a usable provider, and a selection failure surfaces as the structured `WebError` the caller routes on — which carries the branchable detail (the missing id or ambiguous candidate set) in its code and message.
123
+
124
+ Selection never depends on registration, config, or HMR order: a capability has an explicit provider id (config `searchProvider`/`fetchProvider`, or the matching env var feeding the same field), or auto-selects when exactly one usable provider is registered; multiple usable providers with no configured id is `WEB_PROVIDER_AMBIGUOUS`, not first-wins.
125
+
126
+ ## Errors
127
+
128
+ `WebError extends HarnessError` ([core.md](core.md) error taxonomy) with a `code: string` (open, like every other seam's error — `LlmError`, `SubagentError`), not a closed union: a provider may raise its own codes without editing `dsh-web`, and consumers must tolerate an unknown code. The codes split by owner. Seam-neutral codes are raised by the shared `WebRuntime` contract: `WEB_PROVIDER_UNAVAILABLE`, `WEB_PROVIDER_CONFIGURED_MISSING`, `WEB_PROVIDER_CONFIGURED_UNAVAILABLE`, `WEB_PROVIDER_AMBIGUOUS`, `WEB_DUPLICATE_PROVIDER` (a registration-time programming error, the analogue of `LlmRuntime`'s `DUPLICATE_ADAPTER`), `WEB_ABORTED`, and `WEB_PROVIDER_ERROR` (the catch-all for a provider's own failure surfaced through the seam, including network/transport failure — DNS, connection refused, TLS). Fetch-transport codes are owned by the `dsh-web-fetch-http` implementation and a different fetch backend need not raise them: `WEB_INVALID_URL`, `WEB_BLOCKED_URL`, `WEB_REDIRECT_BLOCKED`, `WEB_FETCH_TOO_LARGE`, `WEB_FETCH_TIMEOUT`, `WEB_UNSUPPORTED_CONTENT_TYPE`.
129
+
130
+ ## The service
131
+
132
+ `WebRuntime` registers search and fetch providers, rejects duplicate ids with `WEB_DUPLICATE_PROVIDER`, and resolves providers at execution time with structured selection errors. The local fetch backend accepts only HTTP(S), rejects credentials, caps redirects, bytes, characters, and time, revalidates every same-origin redirect hop, and decodes the body; the tool owns presentation. The local backend does not block private-network targets; do not enable `web_fetch` where it can reach sensitive internal ones.
133
+
134
+ <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
135
+
136
+ <a id="cordis-surface"></a>
137
+
138
+ ## Cordis API
139
+
140
+ Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
141
+
142
+ <a id="ctxweb--webruntime"></a>
143
+
144
+ ### `ctx.web` — `WebRuntime`
145
+
146
+ The web access service. Registered as `ctx.web` (one instance per context).
147
+
148
+ Selection semantics (resolved at execution time, never order-dependent):
149
+
150
+ - A configured id that is registered and `available()` → that provider.
151
+ - A configured id not registered → `WEB_PROVIDER_CONFIGURED_MISSING`.
152
+ - A configured id registered but unavailable → `WEB_PROVIDER_CONFIGURED_UNAVAILABLE`.
153
+ - No id configured, exactly one registered usable provider → that provider.
154
+ - No id configured, multiple usable providers → `WEB_PROVIDER_AMBIGUOUS`.
155
+ - No id configured, no usable provider → `WEB_PROVIDER_UNAVAILABLE`.
156
+
157
+ ```ts cordis-catalog
158
+ /**
159
+ * Register a search provider. Throws {@link WebError} `WEB_DUPLICATE_PROVIDER`
160
+ * if its id is already registered for search. Returns a disposer; disposed
161
+ * with the calling fiber.
162
+ * @param provider - the provider; its `id` is the registry key.
163
+ * @returns the disposer that unregisters the provider.
164
+ */
165
+ registerSearchProvider(provider: WebSearchProvider): () => void
166
+
167
+ /**
168
+ * Register a fetch provider. Throws {@link WebError} `WEB_DUPLICATE_PROVIDER`
169
+ * if its id is already registered for fetch. Returns a disposer; disposed
170
+ * with the calling fiber.
171
+ * @param provider - the provider; its `id` is the registry key.
172
+ * @returns the disposer that unregisters the provider.
173
+ */
174
+ registerFetchProvider(provider: WebFetchProvider): () => void
175
+
176
+ /**
177
+ * Run one search through the selected provider. Resolves the provider at call
178
+ * time with the selection rules above; throws {@link WebError} when the
179
+ * capability cannot run. The seam enforces `request.maxResults` on the result:
180
+ * if the provider over-returns, `sources[]` is truncated and `truncated` set.
181
+ * @param request - the query and optional result limit.
182
+ * @param signal - optional cancellation signal forwarded to the provider.
183
+ * @returns the provider's results, capped to `request.maxResults`.
184
+ */
185
+ async search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult>
186
+
187
+ /**
188
+ * Retrieve one URL through the selected provider. Resolves the provider at
189
+ * call time with the selection rules above; throws {@link WebError} when the
190
+ * capability cannot run. A non-2xx response is a result, not a throw.
191
+ * @param request - the URL plus retrieval options.
192
+ * @param signal - optional cancellation signal forwarded to the provider.
193
+ * @returns the retrieval outcome; non-2xx responses resolve descriptively.
194
+ */
195
+ async fetch(request: WebFetchRequest, signal?: AbortSignal): Promise<WebFetchResult>
196
+ ```
197
+
198
+ Source: [`packages/web/web/src/index.ts:74`](../../packages/web/web/src/index.ts)
199
+ <!-- END GENERATED cordis-surface -->
@@ -0,0 +1,199 @@
1
+ # Web 访问
2
+
3
+ [English](web.md) | 中文
4
+
5
+ Web 访问 seam 是一个[能力 seam](../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md),在同一个 `ctx.web` 服务上横跨**两项操作**(search 与 fetch),并拆分到多个包:Service Definition([dsh-web](../../packages/web/web),`ctx.web` + 提供方注册表)、Service Provider([dsh-web-search-exa](../../packages/web/web-search-exa)、[dsh-web-search-perplexity](../../packages/web/web-search-perplexity)、[dsh-web-search-deepseek](../../packages/web/web-search-deepseek)、[dsh-web-fetch-http](../../packages/web/web-fetch-http))与 Consumer([dsh-tool-web](../../packages/web/tool-web),即 `web_search`/`web_fetch` 工具 schema)。Web 是**一项可选能力**,不属于 agent loop(智能体循环)主干,因此其词汇定义在此而非 [core.md](core.md) 中。更换 search 提供方不会改变模型提交查询的方式,更换 fetch 提供方也不会改变模型请求 URL 的方式。
6
+
7
+ 源码:[`packages/web/web/src/types.ts`](../../packages/web/web/src/types.ts)
8
+
9
+ ## 为什么一项能力包含两项操作
10
+
11
+ 搜索与抓取既不共享请求 schema,也不共享业务逻辑,但它们被有意设计为同一个 `ctx.web` 中间层:一个提供方选择策略的所有者、一套中止与错误词汇,以及一个面向产品的「此 harness 如何访问 Web」配置界面。代价是服务上并行的 `searchX`/`fetchX` 方法对;这种并行是有意为之,而不是遗漏了可抽取的共性。提供方注册的是**能力**(`WebSearchProvider` 或 `WebFetchProvider`),而非工具;面向模型的名称、schema、提示词引导与展示全部集中在唯一的消费方 `dsh-tool-web` 中。
12
+
13
+ ## 搜索请求与结果
14
+
15
+ 面向模型的工具参数仅为一个 `query`;`maxResults` 是消费方自有的上限(`dsh-tool-web` 的 `searchMaxResults` 配置,默认 `8`),通过 seam 传递并在返回时强制执行——如果提供方返回超量,seam 截断 `sources[]` 并设置 `truncated`。
16
+
17
+ ```ts type-equiv
18
+ /**
19
+ * What one search-capable backend can return. The model-facing argument is just
20
+ * a query; `maxResults` is a `dsh-tool-web`-layer bound passed through unchanged
21
+ * and enforced on the way back by the seam (see {@link WebSearchResult}).
22
+ */
23
+ interface WebSearchRequest {
24
+ readonly query: string
25
+ /**
26
+ * Upper bound on returned sources; the seam truncates to it. Omitted = no
27
+ * bound. `dsh-tool-web` always sets it. A provider whose API supports a
28
+ * result-count control (Exa's `numResults`) should apply it at the request
29
+ * layer as a cost/latency optimization; the seam enforces the bound
30
+ * regardless.
31
+ */
32
+ readonly maxResults?: number
33
+ }
34
+ ```
35
+
36
+ ```ts type-equiv
37
+ /**
38
+ * Normalized search outcome. `content` is optional provider-generated answer
39
+ * text or summary (Exa and DeepSeek return none; Perplexity returns a
40
+ * generated answer).
41
+ * `sources[]` is the portable citation shape. `truncated` is set by the seam
42
+ * when it cut `sources[]` down to `maxResults`.
43
+ */
44
+ interface WebSearchResult {
45
+ /** Optional provider-generated answer text, search context, or summary. */
46
+ readonly content?: string
47
+ /** Citeable sources, already truncated to the request's `maxResults`. */
48
+ readonly sources: readonly WebSearchSource[]
49
+ /** True when the seam dropped sources to honor `maxResults`. */
50
+ readonly truncated: boolean
51
+ }
52
+ ```
53
+
54
+ ```ts type-equiv
55
+ /**
56
+ * One citeable source. A source always has a URL; `title`, `snippet`, and
57
+ * `publishedAt` are optional because not every provider returns them — forcing
58
+ * adapters to invent them would make the seam lie (Perplexity citations may be
59
+ * URL-only). `dsh-tool-web` renders `title ?? hostname(url)` for display.
60
+ */
61
+ interface WebSearchSource {
62
+ readonly url: string
63
+ readonly title?: string
64
+ readonly snippet?: string
65
+ /** Publication/crawl timestamp as a provider-supplied ISO-8601 string. */
66
+ readonly publishedAt?: string
67
+ }
68
+ ```
69
+
70
+ ## 抓取请求与结果
71
+
72
+ ```ts type-equiv
73
+ /**
74
+ * What one fetch-capable backend is asked to retrieve. The request deliberately
75
+ * omits timeout, format, prompt, and extraction controls: cancellation is a
76
+ * direct execution argument, while presentation and higher-level LLM concerns
77
+ * belong outside safe retrieval.
78
+ */
79
+ interface WebFetchRequest {
80
+ readonly url: string
81
+ }
82
+ ```
83
+
84
+ HTTP 状态码是被抓取资源状态的一部分,不自动视为失败:即使一次成功的网络抓取收到 `404` 或 `500` 响应,也仍会产出一个 `WebFetchResult`,其中包含状态码和长度受限的已解码正文。`url` 是经过允许的重定向后的最终 URL。`WebError` 仅用于无法安全获取或表示资源的情况。
85
+
86
+ ```ts type-equiv
87
+ /**
88
+ * Normalized fetch outcome. A successful network fetch of a non-2xx response is
89
+ * a result, not an error: the status code is part of the fetched resource
90
+ * state. {@link WebError} is reserved for failures to safely retrieve or
91
+ * represent the resource.
92
+ */
93
+ interface WebFetchResult {
94
+ /** The final URL after allowed redirects (the request URL is in the request). */
95
+ readonly url: string
96
+ /** HTTP status code of the fetched response. */
97
+ readonly statusCode: number
98
+ /** Decoded body, classified by content kind. */
99
+ readonly body: WebFetchBody
100
+ /** True when the provider capped the decoded body. */
101
+ readonly truncated: boolean
102
+ }
103
+ ```
104
+
105
+ ```ts type-equiv
106
+ /**
107
+ * The decoded body of a fetched resource. A CLOSED discriminated union owned by
108
+ * `dsh-web`: the provider decodes the kind and `dsh-tool-web` renders it, so a
109
+ * new kind is a coordinated change across known packages, not a plugin
110
+ * extension. Consumers `switch` on `kind` ending in `default: assertNever(...)`
111
+ * so adding a kind breaks compilation at every consumer until handled. Each arm
112
+ * stays its own object literal even where fields coincide, so an arm can gain
113
+ * fields the others lack.
114
+ */
115
+ type WebFetchBody =
116
+ | { readonly kind: 'html'; readonly content: string }
117
+ | { readonly kind: 'text'; readonly content: string }
118
+ ```
119
+
120
+ ## 提供方可用性
121
+
122
+ 提供方的 `available(): boolean` 是一个廉价的本地检查(凭证是否存在、配置是否可解析),**禁止发起网络调用**。它是执行时选择提供方的输入,而不是健康检查系统:`search()`/`fetch()` 会读取它来选择可用的提供方。选择失败时,调用方会收到可据以分支处理的结构化 `WebError`;其错误代码和消息会说明缺失的 id 或存在歧义的候选集。
123
+
124
+ 选择从不依赖注册顺序、配置顺序或 HMR(热模块替换)顺序:一项能力要么有显式的提供方 id(配置 `searchProvider`/`fetchProvider`,或填充同一字段的对应环境变量),要么在恰好只有一个可用提供方注册时自动选择;如果存在多个可用提供方却未配置 id,则抛出 `WEB_PROVIDER_AMBIGUOUS`,而不会选用最先注册的提供方。
125
+
126
+ ## 错误
127
+
128
+ `WebError extends HarnessError`([core.md](core.md) 错误分类体系),带有 `code: string`(开放式,与其他 seam 的错误一致——`LlmError`、`SubagentError`),而非封闭联合类型:提供方可以在不修改 `dsh-web` 的情况下抛出自己的错误代码,消费方必须容忍未知错误代码。错误代码按所有者划分。共享的 `WebRuntime` 约定会抛出与 seam 无关的错误代码:`WEB_PROVIDER_UNAVAILABLE`、`WEB_PROVIDER_CONFIGURED_MISSING`、`WEB_PROVIDER_CONFIGURED_UNAVAILABLE`、`WEB_PROVIDER_AMBIGUOUS`、`WEB_DUPLICATE_PROVIDER`(注册时的编程错误,类似 `LlmRuntime` 的 `DUPLICATE_ADAPTER`)、`WEB_ABORTED`,以及 `WEB_PROVIDER_ERROR`(提供方自身故障经 seam 暴露时使用的兜底代码,包括 DNS、连接被拒绝、TLS 等网络或传输故障)。抓取传输层错误代码由 `dsh-web-fetch-http` 实现拥有,不同的抓取后端无需抛出它们:`WEB_INVALID_URL`、`WEB_BLOCKED_URL`、`WEB_REDIRECT_BLOCKED`、`WEB_FETCH_TOO_LARGE`、`WEB_FETCH_TIMEOUT`、`WEB_UNSUPPORTED_CONTENT_TYPE`。
129
+
130
+ ## 服务
131
+
132
+ `WebRuntime` 注册搜索与抓取提供方,以 `WEB_DUPLICATE_PROVIDER` 拒绝重复 id,并在执行时以结构化的选择错误解析提供方。本地抓取后端仅接受 HTTP(S)、拒绝凭证、限制重定向次数、字节数、字符数和时间、对每一次同源重定向跳转重新进行安全校验,并解码正文;展示由工具负责。本地后端不会拦截私有网络目标;在能够触及敏感内部目标的环境中,禁止启用 `web_fetch`。
133
+
134
+ <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
135
+
136
+ <a id="cordis-surface"></a>
137
+
138
+ ## Cordis API
139
+
140
+ Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
141
+
142
+ <a id="ctxweb--webruntime"></a>
143
+
144
+ ### `ctx.web` — `WebRuntime`
145
+
146
+ The web access service. Registered as `ctx.web` (one instance per context).
147
+
148
+ Selection semantics (resolved at execution time, never order-dependent):
149
+
150
+ - A configured id that is registered and `available()` → that provider.
151
+ - A configured id not registered → `WEB_PROVIDER_CONFIGURED_MISSING`.
152
+ - A configured id registered but unavailable → `WEB_PROVIDER_CONFIGURED_UNAVAILABLE`.
153
+ - No id configured, exactly one registered usable provider → that provider.
154
+ - No id configured, multiple usable providers → `WEB_PROVIDER_AMBIGUOUS`.
155
+ - No id configured, no usable provider → `WEB_PROVIDER_UNAVAILABLE`.
156
+
157
+ ```ts cordis-catalog
158
+ /**
159
+ * Register a search provider. Throws {@link WebError} `WEB_DUPLICATE_PROVIDER`
160
+ * if its id is already registered for search. Returns a disposer; disposed
161
+ * with the calling fiber.
162
+ * @param provider - the provider; its `id` is the registry key.
163
+ * @returns the disposer that unregisters the provider.
164
+ */
165
+ registerSearchProvider(provider: WebSearchProvider): () => void
166
+
167
+ /**
168
+ * Register a fetch provider. Throws {@link WebError} `WEB_DUPLICATE_PROVIDER`
169
+ * if its id is already registered for fetch. Returns a disposer; disposed
170
+ * with the calling fiber.
171
+ * @param provider - the provider; its `id` is the registry key.
172
+ * @returns the disposer that unregisters the provider.
173
+ */
174
+ registerFetchProvider(provider: WebFetchProvider): () => void
175
+
176
+ /**
177
+ * Run one search through the selected provider. Resolves the provider at call
178
+ * time with the selection rules above; throws {@link WebError} when the
179
+ * capability cannot run. The seam enforces `request.maxResults` on the result:
180
+ * if the provider over-returns, `sources[]` is truncated and `truncated` set.
181
+ * @param request - the query and optional result limit.
182
+ * @param signal - optional cancellation signal forwarded to the provider.
183
+ * @returns the provider's results, capped to `request.maxResults`.
184
+ */
185
+ async search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult>
186
+
187
+ /**
188
+ * Retrieve one URL through the selected provider. Resolves the provider at
189
+ * call time with the selection rules above; throws {@link WebError} when the
190
+ * capability cannot run. A non-2xx response is a result, not a throw.
191
+ * @param request - the URL plus retrieval options.
192
+ * @param signal - optional cancellation signal forwarded to the provider.
193
+ * @returns the retrieval outcome; non-2xx responses resolve descriptively.
194
+ */
195
+ async fetch(request: WebFetchRequest, signal?: AbortSignal): Promise<WebFetchResult>
196
+ ```
197
+
198
+ Source: [`packages/web/web/src/index.ts:74`](../../packages/web/web/src/index.ts)
199
+ <!-- END GENERATED cordis-surface -->
@@ -0,0 +1,6 @@
1
+ # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
2
+ # side as of the last confirmed-consistent state. Both languages carry equal authority;
3
+ # after editing either side, bring the other along and re-record with:
4
+ # pnpm run verify-translation-pairing --write docs/subsystems/workflow.md
5
+ workflow.md: f2c987fbc2ca3a334c55bf0b299764e2b3e6bb06
6
+ workflow.zh.md: b4e6e6afe73b20f1da39c1548c072cf7aeb1f441