12 个章节覆盖从安装到源码构建的完整链路。文中所述行为均以本移植版的实际实现为准，与上游的差异单独成章（第 9 章）。 Twelve chapters cover the whole path from installing to building from source. Everything described here reflects this port's actual behaviour; differences from upstream get their own chapter (chapter 9).
织码（Weave Code）是一款运行在 HarmonyOS 2in1 设备上的代码编辑器。它直接承载 Phoenix Code 的完整生产发行版，而不是重新实现一套编辑器界面。 Weave Code (织码) is a code editor for HarmonyOS 2in1 devices. It runs the complete Phoenix Code release build rather than reimplementing an editor UI of its own.
| 项目Item | 值Value |
|---|---|
| 名称Name | 织码（Weave Code）Weave Code (织码) |
| 版本Version | 1.0.0 · 包名bundle com.dhuzcs.weavecode |
| 平台Platform | HarmonyOS · 2in1 |
| 上游内核Upstream core | Phoenix Code 5.5.6-0（AGPL-3.0-or-later） |
应用启动后，ArkWeb 组件拦截内部安全地址 https://phoenix.local/，从安装包内直接返回编辑器资源。它不会访问同名的外部站点，全部资源随包分发。
At launch, the ArkWeb component intercepts the internal secure origin https://phoenix.local/ and serves editor assets straight out of the installed package. The external site of the same name is never contacted — everything ships inside the package.
采用 HTTPS 同源环境，是为了让 fetch、ES 模块、iframe、Web Worker 与 IndexedDB 都能正常使用，并能为脚本、样式、字体、图片、音视频与 WASM 返回正确的资源类型。
The HTTPS same-origin setup exists so fetch, ES modules, iframes, Web Workers and IndexedDB all work, and so scripts, styles, fonts, images, media and WASM are served with the correct content types.
因为所有资源都在包内，断网也能编辑、预览、搜索与保存；只有 AI 助手需要联网。 Because every asset is inside the package, you can edit, preview, search and save offline; only the AI assistant needs a network.
与旧版不同：本移植版已移除独立的启动页。启动即进入编辑界面，新建项目改为按需弹出的模态对话框，因此不会再出现“先经过一层页面才能开始工作”的情况。 Changed from earlier builds: this port removed the standalone start screen. Launching goes straight into the editor, and New Project is now an on-demand modal dialog — no extra page stands between you and your work.
| 阶段Stage | 说明Detail |
|---|---|
| 权限激活Permission activation | 恢复上次授权过的文件夹访问权限（长期授权）Re-activates long-term access to previously authorised folders |
| 状态读取State restore | 读取已打开项目列表、打开的文件与未保存修改记录Reads the open project list, open files and unsaved-change records |
| 界面加载UI load | 加载编辑器资源并进入主界面Loads editor assets and enters the main UI |
/mnt/<文件夹名>/。
The system remembers that folder. It then appears in the editor as a virtual mount at a path like /mnt/<folder-name>/.
编辑器的欢迎界面提供两个快捷入口：最近项目（历史打开过的路径）与已打开的项目（当前仍处于挂载状态的项目）。点击即可直接进入。 The editor's welcome view offers two shortcuts: Recent projects (paths you have opened before) and Open projects (those still mounted). Click either to jump straight in.
已知限制：项目已打开 → 重启应用 → 再次点击该项目，可能无法打开。原因是目录授权需要在用户操作仍然有效时重新发起，重启后保留的旧挂载句柄已经失效。 Known limitation: when a project is already open, then the app is restarted, clicking that project again may fail. Folder authorisation must be re-requested while the user gesture is still valid, and the mount handle kept across a restart is stale.
临时规避：重新用 文件 → 打开文件夹 选择同一个文件夹即可继续工作。该问题的定位信息与复现规律，欢迎提交到问题反馈页。 Workaround: use File → Open Folder and pick the same folder again to carry on. Reproduction details are welcome on the feedback page.
打开 HTML 文件后启动实时预览面板，保存或输入时页面会即时更新，无需手动刷新，也无需在外部浏览器之间来回切换。 Open an HTML file, start the live preview pane, and the page updates as you type or save — no manual refresh, no switching to an external browser.
| 能力Capability | 说明Detail |
|---|---|
| 应用内渲染In-app rendering | 把项目的 HTML、样式、脚本、图片、音视频与字体转换成内联资源直接渲染，不依赖外部预览域名，也不需要 Service WorkerTurns the project's HTML, styles, scripts, images, media and fonts into inline assets and renders them directly — no external preview domain, no service worker |
| 可视化检查器Visual inspector | 点选页面元素直接调整样式，改动会写回你的源文件，而不是只停留在预览层Click an element to adjust its styles; edits are written back to your source files instead of only touching the preview |
| 外部浏览器查看Open in a browser | 需要更大视图时，可把预览交给系统浏览器打开When you need more room, hand the preview off to the system browser |
预览控制台里出现 sandbox 相关提示属正常现象：预览内容在隔离容器中渲染，这是安全设计而非故障。 Sandbox-related messages in the preview console are normal: preview content renders inside an isolated container. That is by design, not a fault.
工具栏上的 Cloud Code 面板是内置的 AI 助手，可以就当前项目对话、请求解释或生成代码。 The Cloud Code panel on the toolbar is the built-in AI assistant. You can chat about the current project, ask for explanations, or generate code.
AI 请求与流式响应兼容 OpenAI 与 Anthropic 两种接口风格；助手也能读取与保存 Markdown 文件，方便把生成内容直接落盘。 Requests and streaming responses work with both OpenAI- and Anthropic-style APIs. The assistant can also read and save Markdown files, so generated content can be written to disk directly.
凭据安全：不要把 API Key 写进项目源码或提交进仓库。应用内保存的 Key 属于本机配置；若你的 Key 曾出现在源码、日志或截图中，请立即轮换。 Credential safety: never put an API key into project source or commit it. Keys stored in the app stay on the device; if yours ever appeared in source, logs or a screenshot, rotate it now.
语法高亮、行号与代码折叠、多光标、自动缩进与括号配对，覆盖常见前端语言。 Syntax highlighting, line numbers and folding, multiple cursors, auto-indent and bracket matching for common web languages.
文件内查找替换、跨文件搜索、快速打开文件、跳转到指定行。 In-file find and replace, cross-file search, quick open, and go-to-line.
在项目内新建、重命名、移动与删除文件，侧栏树实时反映磁盘变动。 Create, rename, move and delete files inside the project; the sidebar tree reflects disk changes immediately.
像改文档一样直接点选页面元素，编辑文字与结构，改动同步写回源码。 Click elements directly as if editing a document; text and structure changes are written back to source.
| 操作Action | 快捷键Shortcut |
|---|---|
| 命令面板Command palette | Ctrl + Shift + P |
| 快速打开文件Quick open | Ctrl + P |
| 查找 / 替换Find / replace | Ctrl + F / Ctrl + H |
| 保存Save | Ctrl + S |
| 侧栏开关Toggle sidebar | Ctrl + B |
| 启动实时预览Start live preview | Ctrl + Alt + P |
快捷键可在扩展与设置中调整；不同键盘布局下部分组合键可能不同。 Keybindings can be changed in extensions and settings; some combinations differ across keyboard layouts.
输入时给出属性、函数与标签补全建议。 Suggests properties, functions and tags as you type.
一键整理 HTML、CSS 与 JavaScript 的缩进与换行。 Tidy indentation and line breaks in HTML, CSS and JavaScript with one command.
基于内置规则提示可疑写法与常见错误。 Flags suspicious patterns and common mistakes using built-in rules.
依赖语言服务器或桌面 Node 运行时的智能能力（例如部分语言的高级提示与静态分析）当前不可用，详见平台能力边界。 Intelligence that needs a language server or desktop Node runtime — such as advanced completion and static analysis for some languages — is not available yet. See Platform boundaries.
扩展管理器可浏览、安装与移除扩展；主题与快捷键方案也在同一处切换。 The extension manager browses, installs and removes extensions; themes and keymaps switch in the same place.
需要 Node 后端或桌面原生进程的扩展无法在当前版本运行，安装后可能不生效。 Extensions that need a Node backend or desktop native process cannot run in this build and may silently do nothing.
本移植版基于 Phoenix Code 上游生产发行版构建，改动集中在宿主环境、文件系统、预览与 AI 四处，以及若干界面行为。 This port is built from the Phoenix Code upstream release. Changes concentrate on the host environment, the file system, preview and AI, plus several UI behaviours.
| 能力Area | 上游做法Upstream | 本移植版This port |
|---|---|---|
| 运行宿主Runtime host | 桌面应用（Electron 或 Tauri）Desktop app (Electron or Tauri) | HarmonyOS ArkWeb 全屏宿主，拦截内部安全地址并从包内返回资源，全离线运行A full-screen HarmonyOS ArkWeb host that intercepts the internal secure origin and serves assets from the package, fully offline |
| 启动界面Start screen | 独立启动页A standalone start page | 移除启动页，启动直接进入编辑器；新建项目改为按需弹出的模态对话框Start page removed; launch goes straight to the editor, and New Project became an on-demand modal |
| 打开文件夹Opening folders | 桌面文件对话框Desktop file dialog | 改用系统目录选择器 + 长期授权，项目以 /mnt/ 虚拟挂载呈现Uses the system folder picker with persistent permission; projects appear as a /mnt/ virtual mount |
| 实时预览Live preview | 依赖公共预览服务与 Service WorkerRelies on a public preview service and a service worker | 应用内渲染器直接生成内联资源，兼容实机的安全策略，不访问外部预览域名An in-app renderer produces inline assets directly, compatible with the device's security policy, and never touches an external preview domain |
| AI 助手AI assistant | 桌面端设置流程Desktop setup flow | 新增 Cloud Code 集成扩展，配置经原生桥保存，支持流式响应与 Markdown 读写A new Cloud Code integrated extension; settings persist via the native bridge, with streaming and Markdown access |
| 外链行为External links | 在应用内打开Opened in-app | 交给系统浏览器打开，避免把外部站点载入编辑器容器Handed to the system browser, so external sites are never loaded inside the editor container |
| 项目状态Project state | 依赖桌面端的会话恢复Desktop session restore | 新增“最近项目 / 已打开的项目”区块与未保存修改恢复提示，状态存于应用本地Added Recent / Open project blocks and unsaved-change recovery prompts; state lives on the device |
| 界面文案UI wording | 通用英文文案Generic English strings | 补充中文本地化文案，并统一产品名为“织码 / Weave Code”Added Chinese localisation strings and unified the product name as “织码 / Weave Code” |
需要留意的细节：本项目刻意让“是否原生壳”的标记保持为“非原生”，以便编辑器走浏览器文件系统通道（而不是桌面版的原生文件通道）——这是有意设计，不是配置错误。若把它强行改成原生模式，反而会破坏打开文件夹的能力。 One deliberate detail: this project intentionally keeps the “native shell” marker off so the editor uses the browser file-system path instead of the desktop native file path. That is a design decision, not a misconfiguration — forcing native mode actually breaks folder opening.
另外，项目文件系统的选择器行为经过构建期补丁加固，缓存清单哈希与部署文件保持一致，避免出现“脚本未生效”的假象。 The project file-system picker is also hardened by a build-time patch, with cache manifest hashes kept in sync with the deployed files so scripts never appear to silently not load.
Phoenix 的纯 Web 能力已完整打包；依赖桌面进程的能力需要逐项做 HarmonyOS 原生桥接。下面这份清单能帮你快速判断哪些功能现在可用。 Phoenix's pure-web capabilities ship complete; anything that relied on desktop processes needs its own HarmonyOS native bridge. Use this list to judge quickly what works today.
| 能力Capability | 状态Status | 说明Notes |
|---|---|---|
| 编辑、查找、格式化Editing, find, format | 可用Available | 纯 Web 能力，完整可用Pure web capability, fully working |
| 实时预览Live preview | 可用Available | 改由应用内渲染器实现Reimplemented with an in-app renderer |
| 扩展与主题Extensions & themes | 大部分可用Mostly available | 纯 Web 扩展可用；需 Node 后端的除外Pure-web extensions work; those needing a Node backend do not |
| Markdown 与 Design ModeMarkdown & Design Mode | 可用Available | 随上游发行版一同提供Ships with the upstream release |
| AI 助手AI assistant | 可用（需联网）Available (needs network) | 经原生桥转发请求，需自备凭据Requests forwarded through the native bridge; bring your own credentials |
| 系统终端System terminal | 不可用Unavailable | 需要可执行 shell 的运行时Requires a runtime able to execute a shell |
| 语言服务器（LSP）Language servers (LSP) | 不可用Unavailable | 需要 Node 运行时承载服务端进程Needs a Node runtime to host the server process |
| 调试器Debugger | 不可用Unavailable | 依赖桌面调试协议与进程控制Depends on desktop debug protocols and process control |
| Git 命令行Git CLI | 不可用Unavailable | 需要系统 git 可执行文件Requires a system git executable |
若该项目此前已打开过、中间重启过应用，这属于已知限制（见第 3 章）。请用 文件 → 打开文件夹 重新授权同一个目录。 If the project was already open and the app was restarted in between, this is the known limitation described in chapter 3. Re-authorise the same directory via File → Open Folder.
这些能力依赖桌面 Node 或原生进程，当前不打包运行时，属于平台能力边界。 These depend on desktop Node or native processes and no runtime is bundled, so they sit outside today's platform boundaries.
先确认入口 HTML 文件选择正确，且引用的资源都在已授权的项目目录内。引用了绝对路径或目录外文件时，预览无法取到内容。 First confirm the correct entry HTML file is selected and every referenced asset lives inside the authorised project directory. Absolute paths or files outside the folder cannot be resolved by the preview.
项目文件本身始终保存在你授权的原始目录里，应用不复制你的源码。应用只在本机保存少量状态：已授权目录、已打开项目列表与未保存修改的记录。 Your project files always stay in the directory you authorised — the app never copies your source. Only small state lives on the device: authorised folders, the open project list, and unsaved-change records.
应用按 PC / 2in1 形态设计与验证（多窗口、键鼠交互、大屏布局）。手机形态尚未适配，因此不会在手机设备上显示入口。 It is designed and verified for PC / 2in1 form factors — multiple windows, keyboard and mouse, large-screen layout. Phone form factors are not adapted yet, so the app does not appear on phones.
在欢迎界面中清除项目状态即可移除已打开项目列表；也可以直接卸载重装应用，只影响应用内的状态记录，不会动你的项目文件。 Clear the project state from the welcome view to empty the open project list; reinstalling the app also works. Both only affect in-app state — your project files are untouched.
仓库分成两部分：上游源码副本与本机移植工程。改 JavaScript 必须重新走上游构建，仅改 HarmonyOS 侧才只需重编应用。 The repository has two halves: an upstream source copy and the local port project. JavaScript changes must go through the upstream build; only HarmonyOS-side changes need just an app rebuild.
| 目录Path | 作用Purpose |
|---|---|
phoenix-main/ | 上游源码副本与构建脚本Upstream source copy and build scripts |
phoenix-main/dist/ | 上游生产发行产物Upstream production build output |
entry/src/main/resources/rawfile/phoenix/ | 随应用打包的运行时资源（由 dist 同步而来）Runtime assets packaged with the app (synced from dist) |
entry/src/main/ets/pages/Index.ets | ArkWeb 宿主、原生桥与本地资源通道ArkWeb host, native bridge and local asset channel |
# 1. 构建上游生产发行物
cd phoenix-main
npm ci
npm run release:prod # 约 1 分钟
# 2. 同步资源到应用（保留许可证文件）
cp -rf dist/. ../entry/src/main/resources/rawfile/phoenix/
# 3. 构建 HarmonyOS 安装包
hvigorw --mode module -p product=default -p module=entry@default \
-p buildMode=debug assembleHap
# 4. 安装（注意使用相对路径）
hdc install -r entry/build/default/outputs/default/entry-default-signed.hap
三个易踩的坑：① 直接改 dist/ 或 rawfile/ 下的散装脚本在运行时不生效，必须重新构建；② 给 hdc install 传绝对路径在部分 shell 中会导致静默失败，请用相对路径；③ 判断安装成功要看 install bundle successfully.，只看到 AppMod finish 不算成功。
Three common traps: (1) editing loose scripts under dist/ or rawfile/ has no runtime effect — rebuild instead; (2) passing an absolute path to hdc install fails silently in some shells — use a relative path; (3) success prints install bundle successfully. — seeing only AppMod finish does not count.
# 清空日志、重启应用、复现问题、导出日志
hdc shell hilog -r
hdc shell aa force-stop com.dhuzcs.weavecode
hdc shell aa start -a EntryAbility -b com.dhuzcs.weavecode
hdc shell hilog -x > logs.txt日志标签速查见问题反馈页的“怎么取日志”一节。 A tag-by-tag reference lives in the “How to capture logs” section of the feedback page.
发布前必做：轮换签名口令与模型 API Key，确认构建配置里的明文凭据已移出仓库，并核对部署资源与缓存清单哈希一致。这些检查项在正式分发前属于阻塞条件。 Before any release: rotate signing passwords and model API keys, make sure plain-text credentials are out of the repository, and verify deployed assets match the cache manifest hashes. These are blocking checks before public distribution.
本站四个页面共用 assets/ 下的样式与脚本；活动页目前固定显示“暂无活动”；问题反馈页把表单提交到 /api.php?a=feedback，投递邮箱由页面内的 FEEDBACK_MAILTO 常量决定。
All four pages share the styles and script under assets/. The events page currently shows a fixed “no events” state; the feedback page posts its form to /api.php?a=feedback, with the delivery mailbox set by the FEEDBACK_MAILTO constant on the page.
页面改动集中在这些位置时，记得同步中英两套文本——本站所有可见文字都成对存在。 When you change content in these places, update both language strings — every visible string on this site exists as a pair.