()
- // 先创建所有目录节点
+ // 先创建所有目录节点。
for (const entry of entries) {
if (entry.is_dir) {
const node: FileTreeNode = { entry, children: [] }
@@ -46,7 +46,7 @@ function buildFileTree(entries: FileEntry[]): FileTreeNode[] {
}
}
- // 再分配所有节点到父目录
+ // 再把所有节点归到父目录下。
for (const entry of entries) {
const parentPath = entry.path.split('/').slice(0, -1).join('/')
if (parentPath && dirMap.has(parentPath)) {
@@ -57,14 +57,14 @@ function buildFileTree(entries: FileEntry[]): FileTreeNode[] {
parent.children!.push({ entry })
}
} else if (!parentPath) {
- // 根级别节点
+ // 根级节点。
if (entry.is_dir) {
rootNodes.push(dirMap.get(entry.path)!)
} else {
rootNodes.push({ entry })
}
} else {
- // 父目录缺失：作为根节点挂载（容错处理，避免节点丢失）
+ // 父目录缺失时挂到根级，避免节点被丢弃。
if (entry.is_dir) {
rootNodes.push(dirMap.get(entry.path)!)
} else {
@@ -99,6 +99,7 @@ function FileTreeItem({ node, depth = 0, dirCache, onLoadDir, onOpenFile }: File
await onOpenFile(node.entry.path)
return
}
+
if (!isLoaded) {
setLocalLoading(true)
try {
@@ -190,13 +191,36 @@ export default function FileTreePanel() {
const [loading, setLoading] = useState(false)
const [error, setError] = useState('')
const [currentPath, setCurrentPath] = useState('')
+ const activeWorkspaceRef = useRef(currentWorkspaceHash)
+ const rootRequestTokenRef = useRef(0)
+ const mountedRef = useRef(true)
+
+ useEffect(() => {
+ return () => {
+ mountedRef.current = false
+ }
+ }, [])
+
+ useEffect(() => {
+ activeWorkspaceRef.current = currentWorkspaceHash
+ }, [currentWorkspaceHash])
const loadDir = useCallback(async (path: string) => {
if (!gatewayAPI) return
+
+ const requestWorkspaceHash = activeWorkspaceRef.current
+
try {
const result = await gatewayAPI.listFiles({ path })
+ if (!mountedRef.current || activeWorkspaceRef.current !== requestWorkspaceHash) {
+ return
+ }
+
const nodes = buildFileTree(result.payload.files)
setDirCache((prev) => {
+ if (!mountedRef.current || activeWorkspaceRef.current !== requestWorkspaceHash) {
+ return prev
+ }
const next = new Map(prev)
next.set(path, nodes)
return next
@@ -207,24 +231,55 @@ export default function FileTreePanel() {
}
}, [gatewayAPI])
- const loadRoot = useCallback(async () => {
+ // loadRoot 在工作区切换时重置文件树状态，并丢弃旧工作区的晚到响应。
+ const loadRoot = useCallback(async (workspaceHash: string) => {
if (!gatewayAPI) return
+
+ const requestToken = rootRequestTokenRef.current + 1
+ rootRequestTokenRef.current = requestToken
+
+ setRootNodes([])
+ setDirCache(new Map())
+ setCurrentPath('')
setLoading(true)
setError('')
+
try {
const result = await gatewayAPI.listFiles({ path: '' })
+ if (
+ !mountedRef.current ||
+ activeWorkspaceRef.current !== workspaceHash ||
+ rootRequestTokenRef.current !== requestToken
+ ) {
+ return
+ }
+
setRootNodes(buildFileTree(result.payload.files))
setCurrentPath('')
} catch (err) {
+ if (
+ !mountedRef.current ||
+ activeWorkspaceRef.current !== workspaceHash ||
+ rootRequestTokenRef.current !== requestToken
+ ) {
+ return
+ }
+
const msg = err instanceof Error ? err.message : 'Failed to load file list'
setError(msg)
console.error('listFiles failed:', err)
} finally {
- setLoading(false)
+ if (
+ mountedRef.current &&
+ activeWorkspaceRef.current === workspaceHash &&
+ rootRequestTokenRef.current === requestToken
+ ) {
+ setLoading(false)
+ }
}
}, [gatewayAPI])
- // openFilePreview 负责复用/创建文件标签，并按需拉取只读预览内容。
+ // openFilePreview 负责复用或创建文件标签，并按需拉取只读预览内容。
const openFilePreview = useCallback(async (path: string) => {
if (!gatewayAPI) return
@@ -248,8 +303,9 @@ export default function FileTreePanel() {
}, [gatewayAPI, openPreviewTab, setPreviewTabContent, setPreviewTabError, setPreviewTabLoading])
useEffect(() => {
- loadRoot()
- }, [loadRoot])
+ activeWorkspaceRef.current = currentWorkspaceHash
+ void loadRoot(currentWorkspaceHash)
+ }, [currentWorkspaceHash, loadRoot])
return (
diff --git a/web/src/utils/format.test.ts b/web/src/utils/format.test.ts
new file mode 100644
index 00000000..5187b267
--- /dev/null
+++ b/web/src/utils/format.test.ts
@@ -0,0 +1,32 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { relativeTime } from './format'
+
+describe('relativeTime', () => {
+ beforeEach(() => {
+ vi.useFakeTimers()
+ vi.setSystemTime(new Date('2026-05-09T12:00:00Z'))
+ })
+
+ afterEach(() => {
+ vi.useRealTimers()
+ })
+
+ it('returns empty string for empty input', () => {
+ expect(relativeTime('')).toBe('')
+ })
+
+ it('returns the original value for invalid timestamps', () => {
+ expect(relativeTime('not-a-time')).toBe('not-a-time')
+ })
+
+ it('returns 刚刚 for times within one minute', () => {
+ expect(relativeTime('2026-05-09T11:59:30Z')).toBe('刚刚')
+ })
+
+ it('returns minute, hour, day, and month suffixes for older timestamps', () => {
+ expect(relativeTime('2026-05-09T11:55:00Z')).toBe('5m')
+ expect(relativeTime('2026-05-09T09:00:00Z')).toBe('3h')
+ expect(relativeTime('2026-05-06T12:00:00Z')).toBe('3d')
+ expect(relativeTime('2026-03-05T12:00:00Z')).toBe('2mo')
+ })
+})
diff --git a/web/src/utils/format.ts b/web/src/utils/format.ts
index 0996efb2..011170af 100644
--- a/web/src/utils/format.ts
+++ b/web/src/utils/format.ts
@@ -10,7 +10,7 @@ export function formatDate(date: Date | string): string {
return d.toLocaleDateString('zh-CN', { month: 'short', day: 'numeric' })
}
-/** 格式化 Token 数量（带 K/M 后缀） */
+/** 格式化 Token 数量，带 K/M 后缀 */
export function formatTokenCount(n: number): string {
if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`
if (n >= 1_000) return `${(n / 1_000).toFixed(1)}K`
@@ -19,25 +19,31 @@ export function formatTokenCount(n: number): string {
/** 截断文本 */
export function truncate(text: string, maxLen: number): string {
- if (text.length <= maxLen) return text
- return text.slice(0, maxLen - 3) + '...'
+ if (text.length <= maxLen) return text
+ return text.slice(0, maxLen - 3) + '...'
}
-/** 绠€鐭浉瀵规椂闂?*/
+/** 返回简短的相对时间文案 */
export function relativeTime(time: string): string {
- if (!time) return ''
- const d = new Date(time)
- if (isNaN(d.getTime())) return time
- const now = Date.now()
- const diff = now - d.getTime()
- const sec = Math.floor(diff / 1000)
- if (sec < 60) return '鍒氬垰'
- const min = Math.floor(sec / 60)
- if (min < 60) return `${min}m`
- const hr = Math.floor(min / 60)
- if (hr < 24) return `${hr}h`
- const day = Math.floor(hr / 24)
- if (day < 30) return `${day}d`
- const mon = Math.floor(day / 30)
- return `${mon}mo`
+ if (!time) return ''
+
+ const d = new Date(time)
+ if (isNaN(d.getTime())) return time
+
+ const now = Date.now()
+ const diff = now - d.getTime()
+ const sec = Math.floor(diff / 1000)
+ if (sec < 60) return '刚刚'
+
+ const min = Math.floor(sec / 60)
+ if (min < 60) return `${min}m`
+
+ const hr = Math.floor(min / 60)
+ if (hr < 24) return `${hr}h`
+
+ const day = Math.floor(hr / 24)
+ if (day < 30) return `${day}d`
+
+ const mon = Math.floor(day / 30)
+ return `${mon}mo`
}
diff --git a/www/en/guide/install.md b/www/en/guide/install.md
index e0fec326..68edbcde 100644
--- a/www/en/guide/install.md
+++ b/www/en/guide/install.md
@@ -63,6 +63,14 @@ neocode --workdir /path/to/your/project
Type natural language in the input box to chat. Type `/` to see local control commands.
+NeoCode also provides a browser-based Web UI:
+
+```bash
+neocode web
+```
+
+Tagged release builds start the Web UI from assets already embedded in the `neocode` binary, so the target machine does not need Node.js or npm. When running from source, a missing `web/dist` still triggers a local frontend build.
+
## 5. First conversation
Try:
diff --git a/www/guide/install.md b/www/guide/install.md
index 6c4f1563..252b516e 100644
--- a/www/guide/install.md
+++ b/www/guide/install.md
@@ -73,7 +73,7 @@ neocode --workdir /path/to/your/project
neocode web
```
-标签发布版执行 `neocode web` 时，如果本地还没有 `web/dist`，会自动使用发布包内的 `web/` 源码执行 `npm install` 和 `npm run build`，然后启动 Web UI。该流程要求当前机器已安装 Node.js 和 npm。
+标签发布版执行 `neocode web` 时，会直接使用二进制内嵌的 Web UI 资源启动，不要求当前机器安装 Node.js 或 npm。
## 5. 第一次对话
@@ -118,7 +118,7 @@ go build ./...
go run ./cmd/neocode
```
-如果你希望从源码仓库直接验证 Web UI，也可以运行 `go run ./cmd/neocode web`。当 `web/dist` 缺失时，命令会自动尝试构建前端；若构建机没有 Node.js/npm，会直接报出依赖缺失提示。
+如果你希望从源码仓库直接验证 Web UI，也可以运行 `go run ./cmd/neocode web`。当 `web/dist` 缺失时，命令会自动尝试构建前端；若构建机没有 Node.js/npm，会直接报出依赖缺失提示。也就是说，只有源码运行场景仍依赖本地前端构建链路。
如果你只想稳定使用，优先使用一键安装方式。源码构建更适合阅读代码、调试功能或参与开发。
diff --git a/www/guide/web-ui.md b/www/guide/web-ui.md
index d4d83ec1..98bfc86d 100644
--- a/www/guide/web-ui.md
+++ b/www/guide/web-ui.md
@@ -14,7 +14,7 @@ neocode web
```
启动后浏览器会自动打开 `http://127.0.0.1:8080`。如果端口被占用，会自动尝试 8081 ~ 8090。
-如果当前目录或发布包内存在 `web/` 源码但还没有 `web/dist`，命令会自动执行 `npm install` 和 `npm run build`。标签发布版使用该能力时，用户机器必须预先安装 Node.js 和 npm。
+标签发布版会直接使用二进制内嵌的 Web UI 资源启动，不要求用户机器安装 Node.js 或 npm。只有在源码仓库运行、且本地缺少 `web/dist` 时，命令才会自动执行 `npm install` 和 `npm run build`。
### 常用参数
@@ -22,7 +22,7 @@ neocode web
|------|--------|------|
| `--http-listen` | `127.0.0.1:8080` | 监听地址（仅允许回环地址） |
| `--open-browser` | `true` | 启动后自动打开浏览器 |
-| `--skip-build` | `false` | 跳过前端构建（dist/ 缺失时会报错；仅在你已准备好预构建资源时使用） |
+| `--skip-build` | `false` | 跳过本地前端构建（若二进制已内嵌资源仍可启动；主要用于源码模式或自备 dist 的场景） |
| `--static-dir` | — | 指定前端静态文件目录 |
| `--log-level` | `info` | 日志级别：debug / info / warn / error |
| `--token-file` | — | 自定义认证 token 文件路径 |
@@ -57,7 +57,7 @@ Web UI 支持两种运行模式，根据启动方式自动选择：
### 浏览器模式
通过 `neocode web` 或直接在浏览器中访问 Gateway 地址时使用。首次连接需要输入 Gateway URL 和 token，配置保存在 sessionStorage 中。
-如果你使用标签发布版，首次运行 `neocode web` 可能先看到前端依赖安装与构建日志；构建完成后会继续启动 Web UI。若机器缺少 Node.js/npm，命令会直接提示安装依赖。
+如果你使用标签发布版，`neocode web` 会直接启动内嵌的 Web UI。若你使用源码仓库运行并且本地没有 `web/dist`，命令才会先执行前端依赖安装与构建；此时如果机器缺少 Node.js/npm，会直接提示安装依赖。
## 核心功能